Erros, Limites de Taxa e Confiabilidade
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.)
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: respeite o retry-after, suavize picos, agrupe em lotes o trabalho offline e use um modelo mais barato (Escolhendo um Modelo) 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.