Erros, Limites de Taxa e Confiabilidade
Intermediário
- Ler o mapa de erros HTTP e saber quais status repetir versus corrigir
- Repetir erros transitórios com backoff exponencial e jitter, com teto
- Lidar com limites de taxa usando retry-after, suavização, lotes e modelos mais baratos
- Isolar seu código de descontinuações e migrações de modelos
Código em produção conversa com um serviço de rede, então deve esperar falhas. Um pouco de estrutura aqui é a diferença entre uma integração instável e uma confiável.
O mapa de erros
Status HTTP típicos que você vai tratar:
| Status | Significado | O que fazer |
|---|---|---|
| 400 | Requisição inválida | Corrija o payload; não repita como está |
| 401 | Chave de API inválida/ausente | Verifique as credenciais |
| 403 | Não permitido | Verifique acesso/permissões |
| 429 | Limite de taxa atingido | Recue e tente novamente (respeite o retry-after) |
| 500/529 | Erro de servidor / sobrecarregado | Tente novamente com backoff |
- Os SDKs expõem isso como exceções tipadas, então você pode ramificar de forma limpa em vez de analisar strings.
Retentativas com backoff
Para erros transitórios (429, 5xx), tente novamente com backoff exponencial + jitter, com um teto:
import time, random
for attempt in range(5):
try:
return client.messages.create(...)
except (RateLimitError, APIStatusError) as e:
if attempt == 4 or not should_retry(e):
raise
time.sleep(min(2 ** attempt + random.random(), 30))
- Muitos SDKs repetem erros transitórios automaticamente — conheça o padrão do seu cliente antes de adicionar o seu próprio, ou você pode acabar duplicando as retentativas.
Limites de taxa
Os limites se aplicam por conta/nível (requisições e tokens por minuto). Quando você atinge um, recebe 429 com dicas de tempo. Estratégias para ficar abaixo do teto:
Guided walkthrough1 of 4
- Quando receber um 429, leia a dica de tempo na resposta e espere esse intervalo antes de tentar novamente.
- Distribua as requisições ao longo do tempo em vez de dispará-las todas de uma vez.
- Mova trabalhos de alto volume e não interativos para o processamento em lote.
- Direcione etapas de alto volume para um modelo mais barato — veja Escolhendo um Modelo.
Veja Escolhendo um Modelo para escolher o modelo certo para etapas de alto volume.
Migração de modelos
Os IDs de modelo são datados/versionados e ficam obsoletos. Proteja-se:
- Leia o ID do modelo a partir da configuração, não de literais espalhados.
- Acompanhe as descontinuações — veja Observatório de Descontinuações e Migração e a tabela de modelos.
- Re-execute suas evals ao trocar de modelo.
- 400/401/403 são culpa sua — corrija a requisição ou as credenciais, não repita às cegas. 429 e 500/529 são passíveis de retentativa.
- Repita erros transitórios com backoff exponencial + jitter, com teto (ex.: min(2 ** attempt + random(), 30)).
- No 429: respeite o retry-after, suavize os picos, agrupe o trabalho offline em lotes e direcione etapas de alto volume para um modelo mais barato.
- Leia os IDs de modelo a partir da configuração, acompanhe as descontinuações e re-execute as evals ao migrar de modelos.