Falhas de API de IA em Produção

As mensagens de erro raramente contam a história toda quando o seu recurso de IA quebra às 2 da manhã. Eu gerenciei integrações da OpenAI e Anthropic por um ano. Aprendi a agrupar as falhas pelo que elas significam para a depuração (debugging).

Lidando com Limites de Taxa (Rate Limits)

Erros 429 da OpenAI têm causas diferentes. Você deve verificar o código de erro para saber como reagir.

  • Limites de requisições por minuto (RPM) se recuperam em segundos.
  • Limites de tokens por minuto (TPM) se recuperam em 60 segundos.
  • O esgotamento da cota mensal permanece quebrado até que você adicione créditos ou o ciclo de faturamento seja resetado.

Não use backoff exponencial para problemas de cota. Isso só fará você perder tempo.

Erros 529 da Anthropic significam que o provedor está sobrecarregado. Trate isso como um erro 503. O problema é do lado deles. Recue e alerte sua equipe.

Lidando com Erros 400

Essas falhas geralmente são culpa sua. Fique atento a estes três padrões:

  • Incompatibilidade de versão do modelo. Você atualizou um nome em um lugar, mas não no seu manipulador de tentativas (retry handler).
  • Transbordamento da janela de contexto (context window overflow). O histórico da conversa ficou grande demais. Isso geralmente acontece devido a uma lógica de truncamento ruim.
  • Falhas de validação de esquema. Sua estrutura JSON possui tipos não suportados ou referências recursivas.

Para corrigir isso, registre (log) o payload completo da requisição para erros 400. Remova (redact) os dados do usuário primeiro. O corpo da resposta dirá exatamente qual campo falhou.

Lidando com Timeouts

Timeouts são difíceis de rastrear porque o provedor não vê nada de errado.

  • Timeout de conexão (Connect timeout). O handshake falhou. Isso acontece durante instabilidades (brownouts) do provedor ou problemas de DNS. Verifique sua rede de saída.
  • Timeout de leitura (Read timeout). O modelo começou, mas não terminou. Seu aplicativo deve lidar com saídas de streaming parciais.
  • Timeout de gateway (504). Seu proxy expirou primeiro. A requisição ainda pode estar sendo executada no provedor. Use deduplicação antes de tentar novamente.

Para depurar, separe o seu timeout de conexão do seu timeout de leitura. Registre o tempo até o primeiro token (time-to-first-token) para encontrar onde reside a latência.

Lidando com Problemas do Provedor

  • Um erro 500 geralmente se resolve com uma tentativa após dois segundos.
  • Um erro 503 significa que o serviço está degradado. Se a página de status do provedor mostrar um incidente, use um circuit breaker.
  • Sempre registre qual versão do modelo falhou. Diferentes modelos possuem diferentes níveis de confiabilidade.

Pare de pular dos logs para o Slack. Verifique a página de status do provedor primeiro. Isso economiza 20 minutos de pânico.

Fonte: https://dev.to/void_stitch/production-ai-api-failures-by-category-what-429s-529s-and-timeouts-are-actually-telling-you-5bo1

Comunidade de aprendizado opcional: https://t.me/GyaanSetuAi