Conteúdo do curso Lição 121 de 250 · Chamando um LLM Real
Chamando um LLM Real

Lidando com Erros de API

Chamadas de rede reais falham, e um cliente de LLM em produção vive ou morre por como ele reage. O instinto mais útil é dividir as falhas em dois baldes: aquelas que valem retrying (um soluço passageiro que provavelmente vai sumir) e aquelas que você deve fix in the request (um bug na sua chamada que nenhuma quantidade de retentativas vai ajudar). O código de status HTTP diz em qual balde você está.

No código real você captura as exceções tipadas do SDK, que cada uma carrega uma .status_code (apenas ilustrativo -> não chamamos a rede):

import anthropic
try:
    resp = client.messages.create(model="claude-opus-5-5", max_tokens=1024,
                                  messages=history)
except anthropic.RateLimitError:          # HTTP 429 -> back off and retry
    ...
except anthropic.APIStatusError as e:     # any other 4xx/5xx, has e.status_code
    if should_retry(e.status_code):
        ...   # retry with backoff
    else:
        raise # 400/401/403/404 -> a bug in YOUR request, surface it

Os buckets, por código de status:

  • Retry -> 408 (request timeout), 409 (conflict), 429 (rate limited), e qualquer erro de servidor de 500 a 599, como 502, 503 (unavailable) ou 529 (overloaded). Estes são transitórios: espere, depois tente de novo. Quando a resposta traz um cabeçalho retry-after, espere pelo menos esse tempo.
  • Corrija a requisição -> 400 (bad request), 401 (bad API key), 403 (forbidden), 404 (wrong model or path). Tentar de novo uma chamada malformada só gasta o orçamento.
  • Unknown -> qualquer outra coisa (incluindo um sucesso como 200): não assuma que é seguro tentar novamente.

Você está construindo duas funções pequenas. classify_error(status) retorna o nome do bucket: "retry", "fix-request", ou "unknown". should_retry(status) retorna o booleano -> True exatamente quando o status está no conjunto de tentativa, caso contrário False.

Esta lição decide se tentar novamente; o espera entre as tentativas é uma habilidade própria. O módulo production-patterns cobre o backoff exponencial (dobrar o atraso a cada tentativa: 1s, 2s, 4s ...), e além disso você ADICIONA jitter -> uma pequena quantidade aleatória de espera extra -> para que uma frota de clientes rejeitados no mesmo instante não tentem todos no mesmo ritmo e sobrecarreguem o servidor novamente (o "thundering herd"). Construa para que a tabela de status retorne várias respostas diferentes (429 -> retry, 400 -> fix-request, 200 -> unknown), o que significa que nenhuma constante única pode passar.

Sua vez

Escreva classify_error(status) retornando "retry" para 408 (request timeout), 409 (conflict), 429 (rate limited) e cada erro de servidor de 500 a 599 (529 significa sobrecarregado), "fix-request" para {400, 401, 403, 404}, e "unknown" para qualquer outra coisa. Escreva should_retry(status) retornando o booleano True exatamente quando classify_error(status) for "retry", caso contrário False. (Esta é a mesma regra que o SDK oficial da Anthropic usa: ele tenta novamente esses status, e erros de conexão, duas vezes por padrão, e espera pelo tempo que um cabeçalho retry-after pedir. Em código real você geralmente configura max_retries em vez de escrever isso você mesmo; escrever uma vez mostra o que ele faz.)

Viu um problema nesta lição? Reporte-o · Pergunte sobre esta lição

Este exercício abre em breve

Termine a lição anterior para que esta seja desbloqueada. O curso inteiro é gratuito, não precisa de conta, e você pode ler esta lição agora mesmo.