Bygg en AI API avbrottsbevisbok innan du lovar SLA-krediter

När en leverantör av uppströmsmodeller har en incident frågar dina kunder inte bara om leverantören var nere. De frågar om deras förfrågningar misslyckades, vilka nycklar och modeller som påverkades, om avbrottet räknas mot din SLA och vilken kredit de ska få. En leverantörsstatussida hjälper, men den kan inte svara på de hyresgästspecifika frågorna av sig själv.

En AI API-gateway bör behandla avbrottsbevis som en förstklassig reskontra: leverantörssignaler, syntetiska undersökningsresultat, symtom på förfrågningsnivå, fönster för hyresgäster, tillskrivningsbeslut och kreditjusteringar. Målet är inte att skapa en snyggare incidenttidslinje. Målet är att göra avbrottsbeslut för kunderna förklarande, repeterbara och resistenta mot både över- och underkreditering.

Vad leverantörsstatussidor kan och inte kan bevisa

Fakta: Atlassian Statuspage avslöjar offentliga API slutpunkter för sammanfattning, status, komponenter, olösta incidenter, incidenter och planerat underhåll. OpenAI och Anthropic publicerar Statuspage-style JSON slutpunkter som inkluderar komponent- och incidentdata. Google Molnet dokumenterar Service Health API:er och instrumentpaneler, och exponerar även folkhälsoinformation genom flöden. Molnleverantörer publicerar också recensioner efter incidenten för vissa evenemang.

De här flödena är användbara indata. De kan berätta att en leverantör erkände en incident, vilken bred komponent som påverkades, och när incidenten rörde sig genom tillstånd som undersöker, identifierade, övervakar, löste eller obduktion. De räcker inte för att avgöra kundkrediter för ett AI API återförsäljarverksamhet-program.

Statussidor släpar ofta efter verklig kundpåverkan. De kan beskriva en bred komponent som chatt, svar, inbäddningar, bilder eller filer utan att vara tydligt mappade till dina modellalias, leverantörskonton, regioner, implementeringar, tjänstenivåer eller godkännandelistor för hyresgäster. De kan inte heller tala om för dig om en specifik kunds förfrågningar misslyckades på grund av uppströmsförsämring, gateway-strypning, förbrukad budget, ogiltig inmatning, timeoutbeteende på klientsidan eller ett lokalt nätverksproblem.

Rekommendation: använd leverantörsstatus som en bevisström, inte som kreditutlösare. Krediterna bör bero på bevis för hyresgästens påverkan och ett avstämningspass efter att förfrågningsloggar, användningsavräkning och uppdateringar av leverantörsincidenter är tillgängliga.

The Ledger Record You Need

Börja med ett hållbart avbrott som kan representera både leverantörsomfattande incidenter och hyresgästspecifik påverkan. Posten bör endast läggas till eller vara versionerad så att senare klassificeringsändringar inte raderar det ursprungliga spåret.

{
  "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"
}

Providerincidenttiden och hyresgästens påverkanstid är separata fält. En leverantör kan rapportera en omfattande incident från 11:30 till 13:00, men en hyresgäst kan ha varit opåverkad eftersom dess tillåtna modeller använde en annan leverantör. En annan hyresgäst kan ha sett fel endast från 11:47 till 12:18 eftersom routing flyttade den till en reservmodell. En tredje kan ha upplevt hög latens men inga misslyckade förfrågningar. Dessa skillnader spelar roll när krediter blir pengar.

Inta tre bevisströmmar

1. Provider Status APIs

Samla in leverantörsstatusdata enligt ett schema och på begäran under incidenter. Lagra rånyttolast-hash, hämtningstid, leverantörskomponentidentifierare, incidenttillstånd, incident-URL eller leverantörsreferens och eventuell textsammanfattning. Skriv inte över gamla tillstånd. Om en incident går från att undersöka till identifierad till övervakning, bevara varje övergång.

Normalisera leverantörskomponenter till dina egna gatewaydimensioner:

• leverantör: OpenAI, Anthropic, Azure OpenAI, Google eller annan uppströms
• yta: chatt, svar, inbäddningar, bilder, batch, ljud, realtid, filer, moderering
• modell eller implementering: uppströmsmodell, internt alias eller molndistributionsnamn
• region: där tillämpligt
• konto eller autentiseringspool: delat konto, hyresgästbundet konto eller BYOK-uppgifter
• tjänstnivå: standard, prioritet, tillhandahållet, batch- eller internt nivånamn

Trade-off: leverantörsstatusintag är billigt och auktoritativt för erkännande, men det kan vara sent, brett eller ofullständigt. Det bör väcka misstankar och hjälpa till med kundkommunikation, men det bör inte automatiskt generera krediter.

2. Syntetiska kanariefåglar

Syntetiska kanariefåglar är små, kontrollerade förfrågningar som skickas via samma gateway-väg som produktionstrafik. De bör täcka kombinationerna du säljer, inte alla möjliga leverantörsfunktioner. Till exempel kan en återförsäljare köra kanariefåglar för varje leverantör, yta, modellnivå och region som används av betalda planer.

Varje kanariefågelresultat bör innehålla:

• canary_id och schemaversion
• leverantör, yta, modell, region, behörighetspool och ruttprofil
• starttid, första bytetid, slutförandetid och timeouttröskel
• HTTP status, leverantörsfelkod, gatewayfelkod och antal försök igen
• latenspercentilsegment, inte bara godkänd eller misslyckad
• request korrelations-ID och redigerad svarsmetadata

Kanarieöarna bör undvika råa kundmeddelanden. Använd fasta, okänsliga uppmaningar och håll svarsvalideringen enkel. En kanariefågel kan verifiera att slutpunkten accepterar förfrågningar, strömmar är klara och latensen håller sig inom en tröskel. Den behöver inte bedöma modellkvaliteten för beslut om avbrottskredit.

Trade-off: kanariefåglar ger oberoende bevis innan kunder rapporterar ett problem. De lägger också till kostnader och kan konsumera kvoter under leverantörsstress. Gas kanariefåglar under aktiva incidenter och undvik aggressivt försök igen som bidrar till uppströmsbelastning.

3. Symtom på verklig begäran

Bevis på begärandenivå är den starkaste källan till påverkan på hyresgäster. Varje gatewaybegäran bör redan ha klient-, nyckel-, användar- eller slutanvändaridentifierare, modellalias, leverantörsväg, region, status, latens, tokenanvändning och faktureringstillstånd. För avbrottsrapportering, lägg till klassificeringsfält som skiljer uppströmssymptom från kund- och gatewayorsaker.

Användbara symptomklasser inkluderar:

• provider_5xx: uppströms HTTP 5XX eller motsvarande leverantörsserverfel
• provider_timeout: inget leverantörssvar före gateway-timeout
• provider_429_spike: uppströmshastighetsgräns över normal baslinje
• stream_abort_upstream: leverantörsströmmen avslutades oväntat
• latency_degraded: slutförd begäran överskred policytröskel
• gateway_throttle: gateway nekade begäran på grund av hyresgästgräns eller rättvisa policy
• customer_error: ogiltig begäran, modell som inte stöds, dålig autentisering eller felaktig nyttolast
• budget_exhausted: utgifter för hyresgäster eller kreditgräns blockerad utskick

Endast de första fem ska normalt räknas som avbrottssymptom, och även då först efter tillskrivning. En topp i uppströms 429:or kan vara ett leverantörsproblem, men det kan också orsakas av att en hyresgäst överskrider sin reserverade genomströmning. En timeout kan vara leverantörsförsämring, men den kan också orsakas av en klientnedkoppling eller en timeout på programnivå som är kortare än din gateway-timeout.

Det är här som en multi-model API gateway för team behöver disciplinerad händelsemodellering. Ruttbeslutet, ett nytt försök, reservresultat, slutligt svar och faktureringsavräkning bör kunna anslutas med korrelations-ID.

Separat leverantörsincident Windows från Tenant Impact Windows

Gör inte kredit till kunder för leverantörens breda incidentvaraktighet. Kreditera dem för den del av incidenten som påverkade deras kvalificerade trafik enligt din policy.

Använd minst fem fönstermarkörer:

• upptäcktstid: när ditt system först upptäckte onormalt beteende
• första berörda begäran: första kvalificerade hyresgästbegäran med ett avbrottssymptom
• leverantörsbekräftelsetid: när uppströmsleverantören publicerade eller bekräftade incidenten
• reduceringstid: när din gateway tillämpade reserv, trafikformning, ruttavstängning eller annan begränsning
• återställningsbekräftelse: när kanariefåglar och verklig trafik kom tillbaka under tröskelvärdena

Påverkansfönstret för hyresgästen kan beräknas per hyresgäst, per nyckel, per modellalias och per tjänstenivå. Till exempel:

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

Denna separation skyddar dig också från överkreditering. Om en hyresgäst inte hade någon trafik under leverantörshändelsen, kan det inte finnas någon kredit. Om en hyresgäst bara skickade till opåverkade modeller kan det inte finnas någon kredit. Om alla misslyckanden var ogiltiga förfrågningar eller budgetavslag, bör incidentrapporten säga det utan att skylla på leverantören.

Definiera kreditpolicy före incidenten

Kreditpolicy bör vara en tabell eller versionskonfiguration, inte en supportbedömning improviserad under press. Policyn behöver inte vara helt automatisk, men den bör tydliggöra reglerna för kvalificering och godkännande.

Inkludera dessa fält:

• berättigade symtom: leverantör 5XX, uppströms timeout, strömavbrott, allvarlig försämring av latens eller andra klasser
• minsta varaktighet: till exempel fem minuter i följd eller ett tröskelvärde för antal berörda förfrågningar
• latenströskel: fast tröskel, percentilbaslinje eller servicenivåspecifikt mål
• exkluderade orsaker: kundfel, budgetförbrukning, hyresgästkontroll, felaktiga förfrågningar, modell som inte stöds, klientavbrott
• försök behandling igen: om framgångsrika reservförfrågningar räknas som misslyckade, försämrade eller minskade
• kreditformel: procentandel av påverkad användning, fast plånboksjustering, planbaserad SLA-kredit eller manuell granskning
• godkännandemyndighet: automatiskt under en gräns, driftgodkännande över det, ekonomigodkännande för stora hyresgäster
• leverantörskredithantering: skickas igenom, delas, behålls eller hanteras separat från kundkrediter
• bevarande av bevis: hur länge incidenter, förfrågningar, kanariefåglar och kredituppteckningar förblir frågebara

Rekommendation: lagra kreditpolicyversionen vid varje preliminärt och slutgiltigt kreditbeslut. Om du reviderar policyn senare bör historiska beslut fortfarande förklara vilka regler som tillämpades vid den tidpunkten.

Sammanställ före slutliga krediter

Under en incident behöver kunderna statusuppdateringar snabbt. Kreditbeslut kan vara provisoriska. Det slutliga kreditpasset bör ske efter att loggarna är klara, händelser med fördröjd användning har avgjorts, återförsök och reservförsök har klassificerats och leverantörens information efter incidenten har granskats.

Ett praktiskt arbetsflöde för avstämning ser ut så här:

1. Skapa eller uppdatera incidentposten från leverantörsstatus, kanariefågelvarningar eller begär symptomtrösklar.
2. Frys den berörda ruttprofilen eller markera den som försämrad så att nya ruttbeslut kan undvika den där det är möjligt.
3. Generera preliminära fönster för hyresgäster från förfrågningsloggar och kanariefågeltidslinjer.
4. Uteslut orsaker på kundsidan och gatewaysidan med hjälp av klassificeringsregler.
5. Sammanfoga användnings- och faktureringsposter så att berörda förfrågningar är knutna till avräknade kostnads- och kunddebiteringsposter.
6. Använd kreditpolicyversionen och skapa preliminära kreditrader.
7. Granska tvetydiga fall, särskilt partiell latensförsämring och värdefulla hyresgäster.
8. Lägg upp slutliga kreditjusteringar i plånboken eller fakturareskontran med länkar tillbaka till incidentposten.

Detta kopplar avbrottshanteringen till unified AI API billing istället för att lämna krediter som manuella anteckningar i en supportärende. Justeringen bör kunna granskas: vem godkände den, vilken policy som tillämpades, vilka förfrågningar som var kvalificerade och om den är slutgiltig eller reversibel.

Exponera kund och partner API visningar

Kunder behöver en tydlig incidentförklaring, inte hela din interna spårningsbutik. Nedströmsplattformar som säljer vidare eller bäddar in din API kan också behöva visa incidentstatus i sina egna portaler. En Partner API-slutpunkt kan avslöja en incidentvy med klientomfattning.

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"]
  }
}

Håll den här vyn begränsad. Inkludera syntetiska kanariefågel-ID, begäran om korrelations-ID, berörda modeller, berörda nycklar och slutlig kreditstatus. Undvik råa uppmaningar och fullständiga svarsinstanser som standard. Om en kund behöver djupare bevis, tillhandahåll en kontrollerad export med redaktions- och auktoriseringskontroller.

Mall för kundincidentrapport

En användbar kundrapport kan vara kort om huvudboken är komplett. Den bör skilja bekräftade fakta från operativ tolkning.

Fakta

• Berörd leverantör och yta
• Fönster för hyresgästen
• Antal kvalificerade misslyckade, tidsgränsade, avbrutna eller försämrade förfrågningar
• Brörda modellalias, regioner och kundnycklar
• Limitation tillämpad och återställningsbekräftelsetid

Gateway Assessment

• Om symptomen tillskrevs leverantören, gatewayen, hyresgästkonfigurationen eller beteendet från kundförfrågningar
• Om reservrutt minskade effekten
• Om incidenten når kreditpolicyns tröskel
• Om krediten är preliminär, godkänd, tillämpad eller nekad

Begränsningar

• Information om leverantörshändelser kan ändras efter offentliggörande efter döden
• Tröskelvärden för latensförsämring är policydefinierade, inte universella
• Förfrågningar som uteslutits på grund av kundfel eller budgetnedslag räknas inte som leverantörsavbrott

Förutsägelser och designsatsningar

Prognos: rapportering av avbrott mot kunder kommer att bli en normal funktion på AI API återförsäljarplattformar, särskilt för SaaS-leverantörer som exponerar AI-funktioner under sitt eget varumärke. När AI-arbetsbelastningar går från experiment till produktion kommer kunderna att förvänta sig samma incidentansvar som de får från leverantörer av molninfrastruktur.

Prognos: leverantörsstatussidor kommer att förbli nödvändiga men otillräckliga. Fler incidenter kommer att involvera partiell försämring: fördröjningstoppar, streamingavbrott, regionala kapacitetsproblem, kvalitetsregressioner, fel i verktygssamtal eller kontospecifikt kvotbeteende. Dessa fall kräver bevis på begäran och på hyresgästnivå.

Rekommendation: bygg redovisningen innan du lovar starka SLA-krediter. Att eftermontera incidentbevis efter ett omtvistat avbrott är dyrt och ofta osäkert.

Aktiveringsbar slutsats

Låt inte leverantörsstatussidor bli din enda sanningskälla för kundkrediter. Bygg en avbrottsbevisbok som sammanfogar leverantörsincidentflöden, syntetiska kanariefåglar, förfrågningssymptom, ruttbeslut, fönster för hyresgäster, faktureringsuppgifter och slutliga kreditjusteringar.

Den minsta användbara versionen är enkel: ta in leverantörsstatus JSON, kör lågvolym kanariefåglar för sålda modellregionnivåer, klassificera begärandefel efter orsak, beräkna fönster för hyresgästens påverkan och tillämpa en versionerad kreditpolicy efter avstämning. Det ger support, ekonomi, teknik och nedströmspartners samma bevisbas. Det låter dig också förklara incidenter utan att blint spegla uppströmsstatussidor eller utfärda manuella goodwillkrediter närhelst en kund klagar.

Relaterad läsning

• kundvända användnings- och justeringsrapporter