Build an AI API Outage Evidence Ledger Before You Promise Customer SLA Credits

Quando un fornitore del modello upstream ha un incidente, i tuoi clienti non si limitano a chiedere se il fornitore era inattivo. Chiedono se le loro richieste non sono andate a buon fine, quali chiavi e modelli sono stati interessati, se l'interruzione conta ai fini dello SLA e quale credito dovrebbero ricevere. Una pagina di stato del provider è utile, ma non può rispondere da sola a domande specifiche del tenant.

Un gateway AI API dovrebbe trattare le prove di interruzione come un registro di prima classe: segnali del fornitore, risultati sintetici dell'indagine, sintomi a livello di richiesta, finestre di impatto del tenant, decisioni di attribuzione e aggiustamenti del credito. L’obiettivo non è creare una sequenza temporale dell’incidente più bella. L'obiettivo è rendere le decisioni relative alle interruzioni rivolte ai clienti spiegabili, ripetibili e resistenti sia al credito eccessivo che a quello insufficiente.

Cosa possono e non possono essere dimostrati le pagine di stato del fornitore

Fatto: Atlassian Statuspage espone API endpoint pubblici per riepilogo, stato, componenti, incidenti irrisolti, incidenti e manutenzione programmata. OpenAI e Anthropic pubblicano endpoint JSON in stile Statuspage che includono dati su componenti e incidenti. Google Cloud documenta le API e i dashboard di Service Health ed espone inoltre informazioni sulla salute pubblica tramite feed. I fornitori di servizi cloud pubblicano anche recensioni post-incidente per alcuni eventi.

Questi feed sono input utili. Possono dirti che un fornitore ha riconosciuto un incidente, quale componente generale è stata interessata e quando l'incidente è passato attraverso stati come investigazione, identificato, monitoraggio, risolto o post mortem. Non sono sufficienti per decidere i crediti cliente per un programma AI API operazioni del rivenditore.

Le pagine di stato spesso registrano un ritardo nell'impatto reale sui clienti. Possono descrivere un componente ampio come chat, risposte, incorporamenti, immagini o file senza eseguire una mappatura chiara agli alias del modello, agli account del provider, alle aree, alle distribuzioni, ai livelli di servizio o alle liste consentite dei tenant. Inoltre, non sono in grado di dirti se le richieste di un cliente specifico non sono riuscite a causa del degrado dell'upstream, della limitazione del gateway, del budget esaurito, dell'input non valido, del comportamento di timeout lato client o di un problema della rete locale.

Raccomandazione: utilizza lo stato del fornitore come flusso di prove, non come fattore di attivazione del credito. I crediti dovrebbero dipendere dalle prove dell'impatto del tenant e da un passaggio di riconciliazione dopo che saranno disponibili i log delle richieste, la liquidazione dell'utilizzo e gli aggiornamenti sugli incidenti del fornitore.

Il registro contabile di cui hai bisogno

Inizia con un record duraturo delle interruzioni che possa rappresentare sia gli incidenti a livello di provider sia l'impatto specifico del tenant. Il record deve essere di sola aggiunta o con versione in modo che le successive modifiche alla classificazione non cancellino la traccia di rilevamento originale.

{
  "incident_id": "inc_2026_05_29_openai_azure_eastus_latency",
  "provider": "azure_openai",
  "provider_account_id": "acct_prod_shared_01",
  "surface": "chat_completions",
  "model_or_deployment": "gpt-4o-prod-eastus",
  "region": "eastus",
  "source_signals": ["provider_status", "synthetic_canary", "request_symptoms"],
  "confidence": "confirmed",
  "provider_started_at": "2026-05-29T11:42:00Z",
  "provider_acknowledged_at": "2026-05-29T12:05:00Z",
  "detected_at": "2026-05-29T11:45:11Z",
  "mitigated_at": "2026-05-29T12:31:44Z",
  "recovered_at": "2026-05-29T12:48:00Z",
  "affected_tenant_ids": ["ten_123", "ten_456"],
  "linked_request_ids": ["req_a", "req_b", "req_c"],
  "credit_policy_version": "sla_2026_04",
  "credit_status": "pending_reconciliation"
}

Il tempo dell'incidente del provider e il tempo dell'impatto del tenant sono campi separati. Un fornitore può segnalare un incidente generale dalle 11:30 alle 13:00, ma un inquilino potrebbe non essere stato interessato perché i suoi modelli consentiti utilizzavano un altro fornitore. Un altro tenant potrebbe aver riscontrato errori solo dalle 11:47 alle 12:18 perché il routing lo ha spostato su un modello di fallback. Un terzo potrebbe aver riscontrato una latenza elevata ma nessuna richiesta non riuscita. Queste differenze contano quando i crediti diventano denaro.

Importa tre flussi di prove

1. API di stato del fornitore

Raccogli i dati sullo stato del fornitore in base a una pianificazione e su richiesta durante gli incidenti. Archivia l'hash del payload non elaborato, il tempo di recupero, gli identificatori dei componenti del fornitore, lo stato dell'incidente, l'URL dell'incidente o il riferimento del fornitore e qualsiasi riepilogo testuale. Non sovrascrivere i vecchi stati. Se un incidente passa dall'indagine all'identificazione al monitoraggio, preserva ogni transizione.

Normalizza i componenti del provider nelle dimensioni del tuo gateway:

• provider: OpenAI, Anthropic, Azure OpenAI, Google o un altro upstream
• superficie: chat, risposte, incorporamenti, immagini, batch, audio, tempo reale, file, moderazione
• modello o distribuzione: modello upstream, alias interno o nome della distribuzione cloud
• regione: dove applicabile
• account o pool di credenziali: account condiviso, account associato al tenant o credenziale BYOK
• livello di servizio: nome del livello standard, prioritario, fornito, batch o interno

Compromesso: l'importazione dello stato del fornitore è economica e autorevole per il riconoscimento, ma potrebbe essere tardiva, generica o incompleta. Dovrebbe sollevare sospetti e facilitare la comunicazione con il cliente, ma non dovrebbe generare automaticamente crediti.

2. Canarini sintetici

I canary sintetici sono piccole richieste controllate inviate attraverso lo stesso percorso gateway del traffico di produzione. Dovrebbero coprire le combinazioni che vendi, non tutte le possibili funzionalità del fornitore. Ad esempio, un rivenditore potrebbe eseguire canary per ogni fornitore, superficie, livello del modello e regione utilizzata dai piani a pagamento.

Ogni risultato Canary deve includere:

• canary_id e versione di pianificazione
• provider, superficie, modello, regione, pool di credenziali e profilo di percorso
• ora di inizio, ora del primo byte, ora di completamento e soglia di timeout
• HTTP stato, codice di errore del provider, codice di errore del gateway e numero di tentativi
• Bucket del percentile di latenza, non solo superato o fallito
• ID di correlazione della richiesta e metadati di risposta oscurati

I canary dovrebbero evitare richieste insensate ai clienti. Utilizza prompt fissi e non sensibili e mantieni semplice la convalida della risposta. Un canary può verificare che l'endpoint accetti le richieste, i flussi vengano completati e la latenza rimanga entro una soglia. Non ha bisogno di giudicare la qualità del modello per le decisioni sul credito di interruzione.

Compromesso: i canarini forniscono prove indipendenti prima che i clienti segnalino un problema. Aggiungono inoltre costi e possono consumare la quota durante lo stress del fornitore. Limita i canary durante gli incidenti attivi ed evita comportamenti aggressivi tra tentativi che contribuiscono al carico upstream.

3. Sintomi della richiesta reale

Le prove a livello di richiesta sono la fonte più efficace per l'impatto del tenant. Ogni richiesta del gateway deve già avere tenant, chiave, identificatore dell'utente o dell'utente finale, alias del modello, percorso del provider, regione, stato, latenza, utilizzo del token e stato di fatturazione. Per il reporting delle interruzioni, aggiungi campi di classificazione che separano i sintomi a monte dalle cause del cliente e del gateway.

Le classi di sintomi utili includono:

• provider_5xx: errore upstream HTTP 5XX o equivalente del server del provider
• provider_timeout: nessuna risposta del provider prima del timeout del gateway
• provider_429_spike: limite di velocità upstream superiore al valore di base normale
• stream_abort_upstream: lo streaming del provider è terminato in modo imprevisto
• latency_degraded: la richiesta completata ha superato la soglia dei criteri
• gateway_throttle: il gateway ha rifiutato la richiesta a causa dei limiti del tenant o delle norme sull'equità
• customer_error: richiesta non valida, modello non supportato, autenticazione errata o payload non valido
• budget_exhausted: spesa dell'inquilino o limite di credito bloccato

Solo i primi cinque dovrebbero normalmente essere considerati sintomi di interruzione e anche in questo caso solo dopo l'attribuzione. Un picco nei 429 upstream può essere un problema del provider, ma può anche essere causato dal superamento del throughput riservato da parte di un tenant. Un timeout può essere dovuto al degrado del provider, ma può anche essere causato da una disconnessione del client o da un timeout a livello di applicazione più breve del timeout del gateway.

È qui che un gateway multi-modello API per i team necessita di una modellazione di eventi disciplinata. La decisione sul percorso, il tentativo di nuovo tentativo, il risultato del fallback, la risposta finale e la liquidazione della fatturazione devono essere unibili tramite ID di correlazione.

Finestre di intervento del provider separate dalle finestre di impatto del tenant

Non accreditare ai clienti la durata complessiva dell'incidente del fornitore. Ringraziali per la parte dell'incidente che ha influito sul loro traffico idoneo ai sensi delle tue norme.

Utilizza almeno cinque indicatori di finestra:

• ora di rilevamento: quando il sistema ha rilevato per la prima volta un comportamento anomalo
• prima richiesta interessata: prima richiesta del tenant idoneo con un sintomo di interruzione
• ora di conferma del fornitore: quando il fornitore upstream ha pubblicato o confermato l'incidente
• Tempo di mitigazione: quando il gateway ha applicato il fallback, il modellamento del traffico, la disattivazione del percorso o un'altra mitigazione
• conferma del recupero: quando i canary e il traffico reale sono tornati al di sotto delle soglie

La finestra di impatto del tenant può essere calcolata per tenant, per chiave, per alias del modello e per livello di servizio. Ad esempio:

tenant_id: ten_123
model_alias: support-fast
eligible_requests: 842
failed_provider_requests: 96
degraded_latency_requests: 211
first_affected_at: 2026-05-29T11:47:08Z
last_affected_at: 2026-05-29T12:22:31Z
mitigation_applied_at: 2026-05-29T12:04:19Z
credit_status: provisional

Questa separazione ti protegge anche dall'accreditamento eccessivo. Se un inquilino non ha avuto traffico durante l'incidente del fornitore, potrebbe non esserci alcun credito. Se un inquilino viene indirizzato solo a modelli non interessati, potrebbe non esserci alcun credito. Se tutti gli errori fossero richieste non valide o negazioni del budget, il rapporto sull'incidente dovrebbe indicarlo senza incolpare il fornitore.

Definire la politica di credito prima dell'incidente

La politica creditizia dovrebbe essere una tabella o una configurazione con versione, non un giudizio di supporto improvvisato sotto pressione. Non è necessario che la policy sia completamente automatica, ma dovrebbe rendere esplicite le regole di idoneità e approvazione.

Includi questi campi:

• sintomi idonei: provider 5XX, timeout upstream, interruzione dello streaming, grave degrado della latenza o altre classi
• durata minima: ad esempio cinque minuti consecutivi o un numero soglia di richieste interessate
• soglia di latenza: soglia fissa, base di riferimento percentile o target specifico per livello di servizio
• cause escluse: errori del cliente, esaurimento del budget, limitazione del tenant, richieste non valide, modello non supportato, disconnessioni del client
• riprova il trattamento: se le richieste di fallback riuscite vengono considerate non riuscite, danneggiate o attenuate
• formula del credito: percentuale di utilizzo interessato, aggiustamento fisso del portafoglio, credito SLA basato sul piano o revisione manuale
• autorità di approvazione: automatica al di sotto di un limite, approvazione delle operazioni al di sopra di tale limite, approvazione finanziaria per grandi tenant
• gestione del credito del fornitore: trasmesso, condiviso, conservato o gestito separatamente dai crediti del cliente
• conservazione delle prove: per quanto tempo i record di incidenti, richieste, canary e crediti rimangono interrogabili

Raccomandazione: archivia la versione della politica di credito in ogni decisione di credito provvisoria e definitiva. Se rivedi le norme in un secondo momento, le decisioni storiche dovrebbero comunque spiegare quali regole erano applicate in quel momento.

Riconcilia prima dei crediti finali

Durante un incidente, i clienti necessitano di aggiornamenti di stato rapidi. Le decisioni sul credito possono essere provvisorie. Il passaggio di credito finale dovrebbe avvenire dopo il completamento dei registri, la risoluzione degli eventi di utilizzo ritardati, la classificazione dei tentativi e dei fallback e la revisione delle informazioni post-incidente del fornitore.

Un flusso di lavoro pratico per la riconciliazione è simile al seguente:

1. Crea o aggiorna il record dell'incidente dallo stato del fornitore, dagli avvisi Canary o dalle soglie dei sintomi della richiesta.
2. Blocca il profilo di percorso interessato o contrassegnalo come danneggiato in modo che le nuove decisioni sul percorso possano evitarlo ove possibile.
3. Genera finestre di impatto provvisorie del tenant dai log delle richieste e dalle tempistiche Canary.
4. Escludi cause lato cliente e lato gateway utilizzando le regole di classificazione.
5. Unisci i record di utilizzo e fatturazione in modo che le richieste interessate siano legate ai record dei costi liquidati e degli addebiti al cliente.
6. Applica la versione della politica di credito e produci righe di credito provvisorie.
7. Esamina i casi ambigui, in particolare il degrado parziale della latenza e i tenant di alto valore.
8. Pubblica gli aggiustamenti finali del credito nel portafoglio o nel registro delle fatture con collegamenti al record dell'incidente.

Ciò collega la gestione delle interruzioni alla AI unificata API fatturazione invece di lasciare crediti come note manuali in un ticket di supporto. L'aggiustamento dovrebbe essere verificabile: chi lo ha approvato, quali norme sono state applicate, quali richieste erano idonee e se è definitivo o reversibile.

Esponi clienti e partner API visualizzazioni

I clienti hanno bisogno di una spiegazione chiara dell'incidente, non dell'intero archivio di tracciamento interno. Anche le piattaforme downstream che rivendono o incorporano il tuo API potrebbero dover mostrare lo stato dell'incidente all'interno dei propri portali. Un endpoint partner API può esporre una visualizzazione dell'incidente con ambito tenant.

GET /partner/incidents/{incident_id}/tenant-impact?tenant_id=ten_123

{
  "incident_id": "inc_2026_05_29_openai_azure_eastus_latency",
  "status": "final",
  "summary": "Elevated upstream latency and intermittent failures affected selected chat requests.",
  "affected_windows": [
    {
      "model_alias": "support-fast",
      "first_affected_at": "2026-05-29T11:47:08Z",
      "last_affected_at": "2026-05-29T12:22:31Z",
      "eligible_failed_requests": 96,
      "eligible_degraded_requests": 211
    }
  ],
  "affected_keys": ["key_live_abc"],
  "credit_status": "applied",
  "credit_adjustment_id": "adj_789",
  "evidence": {
    "canary_ids": ["canary_chat_eastus_01"],
    "sample_request_ids": ["req_a", "req_b"]
  }
}

Mantieni l'ambito di questa visualizzazione. Includi ID Canary sintetici, ID di correlazione delle richieste, modelli interessati, chiavi interessate e stato del credito finale. Evita prompt non elaborati e corpi di risposta completi per impostazione predefinita. Se un cliente ha bisogno di prove più approfondite, fornisci un'esportazione controllata con controlli di redazione e autorizzazione.

Modello di rapporto sull'incidente del cliente

Un report cliente utile può essere breve se il registro è completo. Dovrebbe distinguere i fatti confermati dall'interpretazione operativa.

Fatti

• Fornitore e superficie interessati
• Finestra di impatto del tenant
• Numero di richieste idonee non riuscite, scadute, interrotte o ridotte
• Alias dei modelli, regioni e chiavi cliente interessati
• Mitigazione applicata e tempo di conferma del ripristino

Valutazione del gateway

• Se i sintomi sono stati attribuiti al provider, al gateway, alla configurazione del tenant o al comportamento della richiesta del cliente
• Se il routing di fallback ha ridotto l'impatto
• Se l'incidente soddisfa la soglia della politica di credito
• Se il credito è provvisorio, approvato, applicato o negato

Limiti

• I dettagli dell'incidente del fornitore potrebbero cambiare dopo la pubblicazione post-mortem
• Le soglie di riduzione della latenza sono definite dai criteri, non universali
• Le richieste escluse in quanto errori del cliente o rifiuti del budget non vengono conteggiate come impatto dell'interruzione del fornitore

Pronostici e scommesse progettuali

Previsione: la segnalazione delle interruzioni rivolte ai clienti diventerà una funzionalità normale delle piattaforme di rivenditori AI API, in particolare per i fornitori SaaS che espongono funzionalità AI con il proprio marchio. Man mano che i carichi di lavoro dell'AI passano dalla sperimentazione alla produzione, i clienti si aspetteranno la stessa responsabilità in caso di incidente che ricevono dai fornitori di infrastrutture cloud.

Previsione: le pagine sullo stato del fornitore rimarranno necessarie ma insufficienti. Un numero maggiore di incidenti comporterà un degrado parziale: picchi di latenza, interruzioni dello streaming, problemi di capacità regionale, regressioni della qualità, errori di chiamata degli strumenti o comportamento delle quote specifiche dell'account. Questi casi richiedono prove a livello di richiesta e di tenant.

Raccomandazione: crea il registro prima di promettere forti crediti SLA. L'aggiornamento delle prove di un incidente dopo un'interruzione contestata è costoso e spesso inconcludente.

Conclusione attuabile

Non lasciare che le pagine sullo stato del fornitore diventino la tua unica fonte di verità per i crediti dei clienti. Crea un registro delle prove di interruzione che unisca feed di incidenti del fornitore, canarini sintetici, sintomi di richiesta, decisioni sul percorso, finestre di impatto del locatario, record di fatturazione e aggiustamenti finali del credito.

La versione minima utile è semplice: importa lo stato del provider JSON, esegui canary a basso volume per i livelli di modello-regione venduti, classifica gli errori delle richieste in base alla causa, calcola le finestre di impatto del tenant e applica una politica di credito con versione dopo la riconciliazione. Ciò fornisce al supporto, alla finanza, alla progettazione e ai partner a valle la stessa base di prove. Ti consente inoltre di spiegare gli incidenti senza rispecchiare ciecamente le pagine di stato a monte o emettere crediti di buona volontà manuali ogni volta che un cliente si lamenta.

Leggi correlati

• Report sull'utilizzo e sugli aggiustamenti rivolti al cliente