Crie um livro-razão de evidência de interrupção de AI API antes de prometer créditos de SLA ao cliente

Quando um provedor de modelo upstream tem um incidente, seus clientes não perguntam apenas se o provedor estava inativo. Eles perguntam se suas solicitações falharam, quais chaves e modelos foram afetados, se a interrupção conta no seu SLA e qual crédito eles deveriam receber. Uma página de status do provedor ajuda, mas não pode responder por si só a essas perguntas específicas do locatário.

Um gateway de IA API deve tratar as evidências de interrupção como um registro de primeira classe: sinais do provedor, resultados de sondagens sintéticas, sintomas no nível da solicitação, janelas de impacto do locatário, decisões de atribuição e ajustes de crédito. O objetivo não é criar um cronograma de incidentes mais bonito. O objetivo é tornar as decisões de interrupção do cliente explicáveis, repetíveis e resistentes tanto ao excesso quanto à falta de crédito.

O que as páginas de status do provedor podem ou não provar

Fato: a Atlassian Statuspage expõe API endpoints públicos para resumo, status, componentes, incidentes não resolvidos, incidentes e manutenção programada. OpenAI e Anthropic publicam endpoints JSON no estilo Statuspage que incluem dados de componentes e incidentes. Google A nuvem documenta APIs e painéis de integridade do serviço e também expõe informações de saúde pública por meio de feeds. Os provedores de nuvem também publicam análises pós-incidentes para alguns eventos.

Esses feeds são entradas úteis. Eles podem informar que um provedor reconheceu um incidente, qual componente amplo foi afetado e quando o incidente passou por estados como investigação, identificação, monitoramento, resolução ou post-mortem. Eles não são suficientes para decidir os créditos do cliente para um programa de AI API operações de revendedor.

As páginas de status geralmente ficam atrás do impacto real no cliente. Eles podem descrever um componente amplo, como bate-papo, respostas, incorporações, imagens ou arquivos, sem mapear claramente seus aliases de modelo, contas de provedor, regiões, implantações, níveis de serviço ou listas de permissões de locatários. Eles também não podem dizer se as solicitações de um cliente específico falharam devido à degradação do upstream, limitação do gateway, orçamento esgotado, entrada inválida, comportamento de tempo limite do lado do cliente ou problema de rede local.

Recomendação: use o status do provedor como um fluxo de evidências, não como o acionador de crédito. Os créditos devem depender da evidência de impacto do locatário e de uma aprovação de reconciliação depois que os registros de solicitação, a liquidação de uso e as atualizações de incidentes do provedor estiverem disponíveis.

O registro contábil que você precisa

Comece com um registro de interrupção durável que possa representar incidentes em todo o provedor e impacto específico do locatário. O registro deve ser somente anexado ou versionado para que alterações posteriores de classificação não apaguem a trilha de detecção original.

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

O horário do incidente do provedor e o horário do impacto do locatário são campos separados. Um provedor pode relatar um incidente amplo das 11h30 às 13h, mas um locatário pode não ter sido afetado porque seus modelos permitidos usaram outro provedor. Outro locatário pode ter visto falhas apenas das 11h47 às 12h18 porque o roteamento o moveu para um modelo substituto. Um terceiro pode ter experimentado alta latência, mas nenhuma solicitação falhou. Essas diferenças são importantes quando os créditos se transformam em dinheiro.

Ingerir três fluxos de evidências

1. APIs de status do provedor

Colete dados de status do provedor de acordo com uma programação e sob demanda durante incidentes. Armazene o hash bruto da carga útil, o tempo de recuperação, os identificadores do componente do provedor, o estado do incidente, o URL do incidente ou a referência do provedor e qualquer resumo de texto. Não substitua estados antigos. Se um incidente passar de investigação para identificação e monitoramento, preserve cada transição.

Normalize os componentes do provedor em suas próprias dimensões de gateway:

• provedor: OpenAI, Anthropic, Azure OpenAI, Google ou outro upstream
• superfície: bate-papo, respostas, incorporações, imagens, lote, áudio, tempo real, arquivos, moderação
• modelo ou implantação: modelo upstream, alias interno ou nome de implantação na nuvem
• região: quando aplicável
• conta ou conjunto de credenciais: conta compartilhada, conta vinculada ao locatário ou credencial BYOK
• nível de serviço: nome do nível padrão, prioritário, provisionado, em lote ou interno

Compensação: a ingestão de status do provedor é barata e confiável para reconhecimento, mas pode ser tardia, ampla ou incompleta. Deve levantar suspeitas e ajudar na comunicação com o cliente, mas não deve gerar créditos automaticamente.

2. Canários Sintéticos

Canários sintéticos são solicitações pequenas e controladas enviadas pelo mesmo caminho de gateway que o tráfego de produção. Eles devem cobrir as combinações que você vende, e não todos os recursos possíveis do fornecedor. Por exemplo, um revendedor pode executar canários para cada provedor, superfície, nível de modelo e região usados por planos pagos.

Cada resultado canário deve incluir:

• canary_id e versão do cronograma
• provedor, superfície, modelo, região, conjunto de credenciais e perfil de rota
• hora de início, hora do primeiro byte, hora de conclusão e limite de tempo limite
• HTTP status, código de erro do provedor, código de erro do gateway e contagem de novas tentativas
• intervalo de percentil de latência, não apenas aprovado ou reprovado
• ID de correlação da solicitação e metadados de resposta editados

Os canários devem evitar solicitações brutas aos clientes. Use prompts fixos e não confidenciais e mantenha a validação de respostas simples. Um canário pode verificar se o endpoint aceita solicitações, se os streams foram concluídos e se a latência permanece dentro de um limite. Não é necessário julgar a qualidade do modelo para decisões de crédito de interrupção.

Compensação: os canários fornecem evidências independentes antes que os clientes relatem um problema. Eles também agregam custos e podem consumir a cota durante o estresse do fornecedor. Acelere os canários durante incidentes ativos e evite comportamentos agressivos de repetição que contribuem para a carga upstream.

3. Sintomas de solicitação real

A evidência em nível de solicitação é a fonte mais forte de impacto sobre o locatário. Cada solicitação de gateway já deve ter locatário, chave, identificador de usuário ou usuário final, alias de modelo, rota do provedor, região, status, latência, uso de token e estado de cobrança. Para relatórios de interrupções, adicione campos de classificação que separam os sintomas upstream das causas do cliente e do gateway.

As classes de sintomas úteis incluem:

• provider_5xx: upstream HTTP 5XX ou erro de servidor do provedor equivalente
• provider_timeout: nenhuma resposta do provedor antes do tempo limite do gateway
• provider_429_spike: limite de taxa upstream acima da linha de base normal
• stream_abort_upstream: o fluxo do provedor terminou inesperadamente
• latency_degraded: solicitação concluída excedeu o limite da política
• gateway_throttle: gateway negou a solicitação devido ao limite de locatário ou política de justiça
• customer_error: solicitação inválida, modelo incompatível, autenticação incorreta ou carga útil malformada
• budget_exhausted: gasto do inquilino ou limite de crédito bloqueado despacho

Normalmente, apenas os cinco primeiros devem ser considerados sintomas de interrupção e, mesmo assim, somente após a atribuição. Um pico nos 429 upstream pode ser um problema do provedor, mas também pode ser causado por um locatário excedendo sua taxa de transferência reservada. Um tempo limite pode ser uma degradação do provedor, mas também pode ser causado por uma desconexão do cliente ou por um tempo limite no nível do aplicativo menor que o tempo limite do gateway.

É aqui que um gateway multimodelo API para equipes precisa de modelagem de eventos disciplinada. A decisão de rota, nova tentativa, resultado de fallback, resposta final e liquidação de cobrança devem ser unidas por ID de correlação.

Separar janelas de incidente do provedor das janelas de impacto do locatário

Não dê crédito aos clientes pela duração ampla do incidente do provedor. Dê crédito a eles pela parte do incidente que afetou o tráfego qualificado de acordo com sua política.

Use pelo menos cinco marcadores de janela:

• tempo de detecção: quando o sistema detectou pela primeira vez um comportamento anormal
• primeira solicitação afetada: primeira solicitação de locatário qualificado com sintoma de interrupção
• tempo de confirmação do provedor: quando o provedor upstream publicou ou confirmou o incidente
• tempo de mitigação: quando seu gateway aplicou substituto, modelagem de tráfego, desativação de rota ou outra mitigação
• confirmação de recuperação: quando canários e tráfego real retornaram abaixo dos limites

A janela de impacto do locatário pode ser calculada por locatário, por chave, por alias de modelo e por nível de serviço. Por exemplo:

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

Essa separação também protege você contra crédito excessivo. Se um inquilino não tiver tráfego durante o incidente do fornecedor, poderá não haver crédito. Se um locatário rotear apenas para modelos não afetados, poderá não haver crédito. Se todas as falhas foram solicitações inválidas ou recusas de orçamento, o relatório do incidente deverá informar isso sem culpar o provedor.

Definir a política de crédito antes do incidente

A política de crédito deve ser uma tabela ou configuração versionada, não um julgamento de suporte improvisado sob pressão. A política não precisa ser totalmente automática, mas deve tornar explícitas as regras de elegibilidade e aprovação.

Inclua estes campos:

• sintomas elegíveis: provedor 5XX, tempo limite de upstream, interrupção de stream, degradação grave de latência ou outras classes
• duração mínima: por exemplo, cinco minutos consecutivos ou um número limite de solicitações afetadas
• limite de latência: limite fixo, linha de base do percentil ou meta específica do nível de serviço
• causas excluídas: erros do cliente, esgotamento do orçamento, limitação de locatários, solicitações malformadas, modelo sem suporte, desconexões do cliente
• tratamento de novas tentativas: se as solicitações de fallback bem-sucedidas contam como com falha, degradadas ou atenuadas
• fórmula de crédito: porcentagem de uso afetado, ajuste fixo da carteira, crédito de SLA baseado em plano ou revisão manual
• autoridade de aprovação: automática abaixo de um limite, aprovação de operações acima dele, aprovação financeira para grandes inquilinos
• manuseio de crédito do provedor: repassado, compartilhado, retido ou tratado separadamente dos créditos do cliente
• retenção de evidências: por quanto tempo os registros de incidentes, solicitações, canário e crédito permanecem consultáveis

Recomendação: armazene a versão da política de crédito em cada decisão de crédito provisória e final. Se você revisar a política posteriormente, as decisões históricas ainda deverão explicar quais regras foram aplicadas naquele momento.

Reconciliar antes dos créditos finais

Durante um incidente, os clientes precisam de atualizações de status rapidamente. As decisões de crédito podem ser provisórias. A aprovação de crédito final deve acontecer depois que os registros forem concluídos, os eventos de uso atrasados forem resolvidos, as novas tentativas e substitutos forem classificados e as informações pós-incidente do provedor forem revisadas.

Um fluxo de trabalho de reconciliação prático é semelhante a este:

1. Crie ou atualize o registro de incidentes a partir do status do provedor, alertas canário ou solicite limites de sintomas.
2. Congele o perfil de rota afetado ou marque-o como degradado para que novas decisões de roteamento possam evitá-lo sempre que possível.
3. Gere janelas provisórias de impacto do locatário a partir de registros de solicitação e cronogramas canário.
4. Exclua causas do lado do cliente e do gateway usando regras de classificação.
5. Junte os registros de uso e faturamento para que as solicitações afetadas sejam vinculadas aos custos liquidados e aos registros de cobrança do cliente.
6. Aplique a versão da política de crédito e produza linhas de crédito provisórias.
7. Revise casos ambíguos, especialmente degradação parcial da latência e locatários de alto valor.
8. Publique os ajustes finais de crédito na carteira ou no livro de faturas com links para o registro do incidente.

Isso vincula o tratamento de interrupções à IA unificada APIfaturamento em vez de deixar créditos como notas manuais em um tíquete de suporte. O ajuste deve ser auditável: quem o aprovou, qual política foi aplicada, quais solicitações eram elegíveis e se é final ou reversível.

Expor clientes e parceiros API Visualizações

Os clientes precisam de uma explicação clara do incidente, não de todo o seu armazenamento de rastreamento interno. As plataformas downstream que revendem ou incorporam seu API também podem precisar mostrar o status do incidente em seus próprios portais. Um endpoint do parceiro API pode expor uma visão de incidente no escopo do locatário.

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

Mantenha o escopo desta visualização. Inclua IDs canários sintéticos, IDs de correlação de solicitação, modelos afetados, chaves afetadas e estado de crédito final. Evite prompts brutos e corpos de resposta completos por padrão. Se um cliente precisar de evidências mais profundas, forneça uma exportação controlada com redação e verificações de autorização.

Modelo de relatório de incidente do cliente

Um relatório útil do cliente pode ser curto se o livro-razão estiver completo. Deve distinguir fatos confirmados de interpretação operacional.

Fatos

• Provedor e superfície afetada
• Janela de impacto do locatário
• Número de solicitações qualificadas com falha, expirado, anulado ou degradado
• Alias de modelos, regiões e chaves de clientes afetados
• Mitigação aplicada e tempo de confirmação de recuperação

Avaliação do gateway

• Se os sintomas foram atribuídos ao provedor, gateway, configuração do locatário ou comportamento de solicitação do cliente
• Se o roteamento alternativo reduziu o impacto
• Se o incidente atende ao limite da política de crédito
• Se o crédito é provisório, aprovado, aplicado ou negado

Limites

• Os detalhes do incidente do provedor podem mudar após a publicação post mortem
• Os limites de degradação de latência são definidos por políticas, não universais
• As solicitações excluídas por erros do cliente ou recusas de orçamento não são contabilizadas como impacto de interrupção do provedor

Previsões e apostas de design

Previsão: relatórios de interrupções voltados para o cliente se tornarão um recurso normal das plataformas de revendedores de IA API, especialmente para fornecedores de SaaS que expõem recursos de IA sob sua própria marca. À medida que as cargas de trabalho de IA passam da experimentação para a produção, os clientes esperam a mesma responsabilidade por incidentes que recebem dos fornecedores de infraestrutura em nuvem.

Predição: páginas de status do provedor permanecerão necessárias, mas insuficientes. Mais incidentes envolverão degradação parcial: picos de latência, interrupções de streaming, problemas de capacidade regional, regressões de qualidade, falhas nas chamadas de ferramentas ou comportamento de cotas específicas da conta. Esses casos exigem evidências em nível de solicitação e de locatário.

Recomendação: crie o livro-razão antes de prometer créditos de SLA fortes. A atualização das evidências de incidente após uma interrupção contestada é cara e muitas vezes inconclusiva.

Conclusão acionável

Não deixe que as páginas de status do provedor se tornem sua única fonte de verdade para créditos de clientes. Crie um livro-razão de evidências de interrupção que reúna feeds de incidentes do provedor, canários sintéticos, sintomas de solicitação, decisões de rota, janelas de impacto do locatário, registros de faturamento e ajustes de crédito finais.

A versão mínima útil é simples: ingerir o status do provedor JSON, executar canários de baixo volume para camadas de região modelo vendidas, classificar falhas de solicitação por causa, calcular janelas de impacto do locatário e aplicar uma política de crédito versionada após a reconciliação. Isso dá aos parceiros de apoio, finanças, engenharia e downstream a mesma base de evidências. Ele também permite que você explique incidentes sem espelhar cegamente páginas de status originais ou emitir créditos de boa vontade manuais sempre que um cliente reclamar.

Leitura relacionada

• relatórios de uso e ajuste voltados para o cliente