Bouw een AI API-grootboek voor uitvalbewijs voordat u klant-SLA-credits belooft

Wanneer een upstream-modelaanbieder een incident heeft, vragen uw klanten niet alleen of de aanbieder niet beschikbaar was. Ze vragen of hun verzoeken zijn mislukt, om welke sleutels en modellen het gaat, of de storing meetelt voor uw SLA en welk krediet ze moeten krijgen. Een providerstatuspagina helpt, maar kan deze huurderspecifieke vragen niet zelf beantwoorden.

Een AI API-gateway moet uitvalbewijs behandelen als een eersteklas grootboek: signalen van leveranciers, synthetische testresultaten, symptomen op verzoekniveau, periodes voor de impact van huurders, attributiebeslissingen en kredietaanpassingen. Het doel is niet om een ​​mooiere incidententijdlijn te creëren. Het doel is om klantgerichte beslissingen over storingen verklaarbaar en herhaalbaar te maken en bestand te zijn tegen zowel te veel als te weinig krediet.

Wat providerstatuspagina's wel en niet kunnen bewijzen

Feit: Atlassian Statuspage toont openbare API eindpunten voor samenvattingen, status, componenten, onopgeloste incidenten, incidenten en gepland onderhoud. OpenAI en Anthropic publiceren JSON-eindpunten in Statuspage-stijl die component- en incidentgegevens bevatten. Google Cloud documenteert Service Health API's en dashboards, en maakt ook informatie over de volksgezondheid openbaar via feeds. Cloudproviders publiceren voor sommige evenementen ook beoordelingen na incidenten.

Deze feeds zijn nuttige input. Zij kunnen u vertellen dat een aanbieder een incident heeft erkend, op welk breed onderdeel het incident betrekking heeft, en wanneer het incident een status heeft doorlopen zoals onderzoeken, identificeren, monitoren, oplossen of postmortem. Ze zijn niet voldoende om te beslissen over de klanttegoeden voor een AI API reseller operations-programma.

Statuspagina's blijven vaak achter bij de echte klantimpact. Ze kunnen een breed onderdeel beschrijven, zoals chat, reacties, insluitingen, afbeeldingen of bestanden, zonder dat ze duidelijk zijn gekoppeld aan uw modelaliassen, provideraccounts, regio's, implementaties, serviceniveaus of toelatingslijsten voor tenants. Ze kunnen u ook niet vertellen of de verzoeken van een specifieke klant zijn mislukt vanwege upstream-degradatie, gateway-throttling, uitgeput budget, ongeldige invoer, time-outgedrag aan de clientzijde of een lokaal netwerkprobleem.

Aanbeveling: gebruik de status van de aanbieder als één bewijsstroom, niet als krediettrigger. Credits moeten afhankelijk zijn van bewijsmateriaal over de impact van de huurder en een afstemmingspas nadat verzoeklogboeken, gebruiksafwikkeling en updates van providerincidenten beschikbaar zijn.

Het grootboekrecord dat u nodig heeft

Begin met een duurzaam storingsrecord dat zowel providerbrede incidenten als huurderspecifieke impact kan weergeven. De record moet alleen worden toegevoegd of van een versie worden voorzien, zodat latere classificatiewijzigingen het oorspronkelijke detectiespoor niet wissen.

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

De incidenttijd van de provider en de impacttijd van de huurder zijn afzonderlijke velden. Een provider kan tussen 11.30 en 13.00 uur een groot incident melden, maar het kan zijn dat één huurder er geen last van heeft gehad omdat de toegestane modellen een andere provider gebruikten. Een andere tenant heeft mogelijk alleen fouten gezien van 11:47 tot 12:18, omdat de routering deze naar een fallback-model heeft verplaatst. Een derde heeft mogelijk een hoge latentie ervaren, maar geen mislukte verzoeken. Deze verschillen zijn van belang als credits geld worden.

Drie bewijsstromen verwerken

1. Providerstatus-API's

Verzamel statusgegevens van providers volgens een schema en op aanvraag tijdens incidenten. Bewaar de onbewerkte payload-hash, ophaaltijd, providercomponent-ID's, incidentstatus, incident-URL of providerreferentie, en eventuele tekstsamenvattingen. Overschrijf geen oude toestanden. Als een incident zich verplaatst van onderzoeken naar geïdentificeerd naar monitoren, bewaar dan elke overgang.

Normaliseer providercomponenten in uw eigen gateway-dimensies:

• provider: OpenAI, Anthropic, Azure OpenAI, Google of een andere upstream
• oppervlak: chat, reacties, insluitingen, afbeeldingen, batch, audio, realtime, bestanden, moderatie
• model of implementatie: upstream-model, interne alias of cloudimplementatienaam
• regio: waar van toepassing
• account of referentiepool: gedeeld account, tenantgebonden account of BYOK-referentie
• Servicelaag: standaard, prioriteit, ingerichte, batch- of interne laagnaam

Afweging: opname van de status van de provider is goedkoop en gezaghebbend voor erkenning, maar kan te laat, breed of onvolledig zijn. Het moet argwaan wekken en helpen bij de communicatie met klanten, maar het mag niet automatisch credits opleveren.

2. Synthetische kanaries

Synthetische canaries zijn kleine, gecontroleerde verzoeken die via hetzelfde gatewaypad worden verzonden als productieverkeer. Ze moeten betrekking hebben op de combinaties die u verkoopt, en niet op alle mogelijke aanbiedersfuncties. Een reseller kan bijvoorbeeld canaries uitvoeren voor elke provider, oppervlakte, modelniveau en regio die wordt gebruikt door betaalde abonnementen.

Elk kanarieresultaat moet het volgende bevatten:

• canary_id en planningsversie
• provider, oppervlak, model, regio, referentiepool en routeprofiel
• starttijd, eerste bytetijd, voltooiingstijd en time-outdrempel
• HTTP status, providerfoutcode, gatewayfoutcode en aantal nieuwe pogingen
• Latentiepercentielbucket, niet alleen geslaagd of mislukt
• correlatie-ID en geredigeerde antwoordmetadata aanvragen

Canarische Eilanden moeten rauwe klantvragen vermijden. Gebruik vaste, niet-gevoelige aanwijzingen en houd de validatie van antwoorden eenvoudig. Een kanarie kan verifiëren dat het eindpunt verzoeken accepteert, de streams voltooid zijn en de latentie binnen een drempelwaarde blijft. Het hoeft de modelkwaliteit niet te beoordelen bij beslissingen over uitvalkredieten.

Afweging: kanaries leveren onafhankelijk bewijs voordat klanten een probleem melden. Ze voegen ook kosten toe en kunnen quota verbruiken tijdens stress bij de provider. Beperk kanaries tijdens actieve incidenten en vermijd agressief gedrag bij opnieuw proberen dat bijdraagt aan de stroomopwaartse belasting.

3. Symptomen van echte verzoeken

Bewijs op verzoekniveau is de sterkste bron voor de impact op huurders. Elke gatewayaanvraag moet al een tenant-, sleutel-, gebruikers- of eindgebruikers-ID, modelalias, providerroute, regio, status, latentie, tokengebruik en factureringsstatus bevatten. Voeg voor storingsrapportage classificatievelden toe die de upstream-symptomen scheiden van de klant- en gateway-oorzaken.

Nuttige symptoomklassen zijn onder meer:

• provider_5xx: upstream HTTP 5XX of gelijkwaardige providerserverfout
• provider_timeout: geen reactie van de provider vóór time-out van de gateway
• provider_429_spike: stroomopwaartse snelheidslimiet boven normale basislijn
• stream_abort_upstream: providerstream onverwacht beëindigd
• latency_degraded: voltooid verzoek heeft de beleidsdrempel overschreden
• gateway_throttle: gateway heeft het verzoek afgewezen vanwege tenantlimieten of eerlijkheidsbeleid
• customer_error: ongeldig verzoek, niet-ondersteund model, slechte authenticatie of onjuist opgemaakte payload
• budget_exhausted: huurdersuitgaven of kredietlimiet geblokkeerde verzending

Normaal gesproken tellen alleen de eerste vijf als storingssymptomen, en zelfs dan alleen na toeschrijving. Een piek in upstream 429's kan een providerprobleem zijn, maar kan ook worden veroorzaakt doordat één tenant de gereserveerde doorvoer overschrijdt. Een time-out kan een verslechtering van de provider zijn, maar kan ook worden veroorzaakt door een client-verbinding of een time-out op applicatieniveau die korter is dan de time-out van uw gateway.

Dit is waar een multi-model API gateway voor teams gedisciplineerde gebeurtenismodellering nodig heeft. De routebeslissing, de nieuwe poging, het terugvalresultaat, het uiteindelijke antwoord en de factureringsafrekening moeten kunnen worden samengevoegd via correlatie-ID.

Afzonderlijke incidentvensters voor provider en impactvensters voor huurder

Geef klanten geen credit voor de brede incidentduur van de aanbieder. Crediteer hen voor het deel van het incident dat invloed heeft gehad op hun in aanmerking komende verkeer onder uw beleid.

Gebruik ten minste vijf raammarkeringen:

• detectietijd: wanneer uw systeem voor het eerst abnormaal gedrag heeft gedetecteerd
• eerste getroffen verzoek: eerste in aanmerking komende tenantverzoek met een storingssymptoom
• Bevestigingstijd van de provider: wanneer de upstreamprovider het incident heeft gepubliceerd of bevestigd
• Beperkingstijd: wanneer uw gateway fallback, traffic shaping, route-uitschakeling of een andere beperking heeft toegepast
• herstelbevestiging: toen canaries en echt verkeer onder de drempelwaarden terugkeerden

De impactperiode voor de tenant kan worden berekend per tenant, per sleutel, per modelalias en per servicelaag. Bijvoorbeeld:

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

Deze scheiding beschermt u ook tegen te veel krediet. Indien een huurder tijdens het providerincident geen verkeer had, kan er geen sprake zijn van tegoed. Als een tenant alleen naar niet-getroffen modellen wordt gerouteerd, is er mogelijk geen tegoed. Als alle mislukkingen ongeldige verzoeken of budgetweigeringen waren, zou het incidentrapport dit moeten vermelden zonder de aanbieder de schuld te geven.

Definieer het kredietbeleid vóór het incident

Kredietbeleid moet een tabel- of versieconfiguratie zijn, en geen ondersteuningsoordeel dat onder druk wordt geïmproviseerd. Het beleid hoeft niet volledig automatisch te zijn, maar het moet de geschiktheids- en goedkeuringsregels expliciet maken.

Voeg deze velden toe:

• in aanmerking komende symptomen: provider 5XX, upstream time-out, stream afgebroken, ernstige vertraging van de latentie of andere klassen
• minimale duur: bijvoorbeeld vijf opeenvolgende minuten of een drempelaantal betrokken verzoeken
• Latentiedrempel: vaste drempel, percentielbasislijn of serviceniveau-specifiek doel
• uitgesloten oorzaken: klantfouten, budgetuitputting, beperking van huurders, onjuist opgemaakte verzoeken, niet-ondersteund model, client-verbinding
• Probeer de behandeling opnieuw: of succesvolle fallback-verzoeken gelden als mislukt, verslechterd of beperkt
• Kredietformule: percentage van het getroffen gebruik, vaste portemonnee-aanpassing, plangebaseerd SLA-tegoed of handmatige beoordeling
• goedkeuringsautoriteit: automatisch onder een limiet, goedkeuring van activiteiten daarboven, financiële goedkeuring voor grote huurders
• Kredietafhandeling van leveranciers: doorgegeven, gedeeld, bewaard of afzonderlijk van klanttegoeden afgehandeld
• bewaren van bewijsmateriaal: hoe lang incident-, verzoek-, kanarie- en kredietgegevens opvraagbaar blijven

Aanbeveling: bewaar de versie van het kredietbeleid bij elke voorlopige en definitieve kredietbeslissing. Als u het beleid later herziet, moeten historische beslissingen nog steeds verklaren welke regels destijds werden toegepast.

Afstemming vóór definitieve aftiteling

Tijdens een incident hebben klanten snel statusupdates nodig. Kredietbeslissingen kunnen voorlopig zijn. De definitieve creditpass moet plaatsvinden nadat de logboeken zijn voltooid, vertraagde gebruiksgebeurtenissen zijn afgehandeld, nieuwe pogingen en terugval zijn geclassificeerd en informatie over post-incidenten van de provider is beoordeeld.

Een praktische afstemmingsworkflow ziet er als volgt uit:

1. Maak of update het incidentrecord op basis van de providerstatus, kanarie-waarschuwingen of vraag symptoomdrempels aan.
2. Bevries het getroffen routeprofiel of markeer het als verslechterd, zodat nieuwe routebeslissingen dit waar mogelijk kunnen vermijden.
3. Genereer voorlopige impactperiodes voor tenants op basis van verzoeklogboeken en canary-tijdlijnen.
4. Sluit oorzaken aan de klant- en gatewayzijde uit met behulp van classificatieregels.
5. Voeg gebruiks- en factureringsgegevens samen, zodat de betrokken verzoeken worden gekoppeld aan de verrekende kosten en klantkostengegevens.
6. Pas de versie van het kredietbeleid toe en maak voorlopige kredietrijen.
7. Bekijk dubbelzinnige gevallen, vooral gedeeltelijke vertraging van de latentie en huurders met een hoge waarde.
8. Post de laatste kredietaanpassingen in de portemonnee of het factuurboek met links naar het incidentrecord.

Hiermee wordt de afhandeling van storingen gekoppeld aan uniforme AI API facturering in plaats van tegoeden achter te laten als handmatige notities in een supportticket. De aanpassing moet controleerbaar zijn: wie heeft deze goedgekeurd, welk beleid werd toegepast, welke verzoeken kwamen in aanmerking en of deze definitief of omkeerbaar is.

Klant en partner zichtbaar maken API Weergaven

Klanten hebben een duidelijke uitleg van incidenten nodig, niet uw hele interne trace-archief. Downstreamplatforms die uw API doorverkopen of insluiten, moeten mogelijk ook de incidentstatus binnen hun eigen portalen weergeven. Een Partner API-eindpunt kan een incidentweergave op tenantniveau weergeven.

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

Houd deze weergave overzichtelijk. Voeg synthetische canary-ID's, aanvraagcorrelatie-ID's, betrokken modellen, betrokken sleutels en uiteindelijke kredietstatus toe. Vermijd standaard onbewerkte aanwijzingen en volledige antwoordteksten. Als een klant diepgaander bewijsmateriaal nodig heeft, zorg dan voor een gecontroleerde export met redactie- en autorisatiecontroles.

Sjabloon voor klantincidentenrapport

Een nuttig klantrapport kan kort zijn als het grootboek compleet is. Het moet bevestigde feiten onderscheiden van operationele interpretatie.

Feiten

• Betrokken provider en oppervlak
• Impactperiode voor huurder
• Aantal in aanmerking komende mislukte, time-out-, afgebroken of gedegradeerde verzoeken
• Betrokken modelaliassen, regio's en klantsleutels
• Mitigatie toegepast en herstelbevestigingstijd

Gatewaybeoordeling

• Of de symptomen werden toegeschreven aan de provider, gateway, tenantconfiguratie of klantverzoekgedrag
• Of fallback-routing de impact verminderde
• Of het incident voldoet aan de kredietbeleidsdrempel
• Of het krediet voorlopig, goedgekeurd, toegepast of geweigerd is

Limieten

• Incidentdetails van de aanbieder kunnen veranderen na postmortale publicatie
• Drempels voor degradatie van de latentie zijn door het beleid gedefinieerd en niet universeel
• Verzoeken die zijn uitgesloten als klantfouten of budgetweigeringen worden niet meegeteld als de impact van uitval van de provider

Voorspellingen en ontwerpweddenschappen

Voorspelling: klantgerichte storingsrapportage wordt een normale functie van AI API resellerplatforms, vooral voor SaaS-leveranciers die AI-functies onder hun eigen merk aanbieden. Naarmate de AI-workloads verschuiven van experimenteren naar productie, verwachten klanten dezelfde verantwoordelijkheid voor incidenten als leveranciers van cloudinfrastructuur.

Voorspelling: providerstatuspagina's blijven noodzakelijk maar onvoldoende. Bij meer incidenten zal sprake zijn van gedeeltelijke degradatie: latentiepieken, streamingonderbrekingen, regionale capaciteitsproblemen, kwaliteitsregressies, mislukte toolcalls of accountspecifiek quotagedrag. In deze gevallen is bewijs op verzoek- en tenantniveau vereist.

Aanbeveling: bouw het grootboek op voordat u sterke SLA-credits belooft. Het achteraf aanpassen van incidentbewijs na een betwiste storing is duur en vaak niet doorslaggevend.

Conclusie waar actie op ondernomen kan worden

Laat de statuspagina's van providers niet uw enige bron van waarheid voor klanttegoeden worden. Bouw een grootboek met bewijsmateriaal voor storingen waarin feeds voor leveranciersincidenten, synthetische canaries, verzoeksymptomen, routebeslissingen, impactperioden voor huurders, factureringsgegevens en definitieve kredietaanpassingen worden samengevoegd.

De minimaal bruikbare versie is eenvoudig: neem de providerstatus JSON op, voer canaries met een laag volume uit voor verkochte modelregiolagen, classificeer mislukte aanvragen op oorzaak, bereken de impactperiodes voor de tenant en pas na afstemming een kredietbeleid met versiebeheer toe. Dat geeft ondersteuning, financiën, engineering en downstream-partners dezelfde wetenschappelijke basis. U kunt er ook incidenten mee uitleggen zonder blindelings upstream-statuspagina's te spiegelen of handmatig goodwillkredieten uit te geven wanneer een klant een klacht indient.

Gerelateerd leesmateriaal

• klantgerichte rapportage over gebruik en aanpassingen