Tipos de Exceção do SDK Python em Resumo
Uma referência densa para cada classe de exceção que o SDK Python anthropic levanta, e se cada uma delas é segura para retentativa.
Como Usar Esta Tabela de Referência
- Procure a exceção que você capturou (ou quer capturar) na tabela principal para seu status HTTP e segurança de retentativa.
- Use a seção "Ordem de Captura" ao escrever uma cadeia
except- a mais específica primeiro. - Use a tabela "O que o SDK já retenta" antes de adicionar sua própria lógica de retentativa em cima das retentativas embutidas do SDK.
Classes de Exceção em Resumo
| Exceção | Status HTTP | Seguro para retentativa? | Causa Típica |
|---|---|---|---|
BadRequestError | 400 | Não | Requisição malformada, valor de parâmetro inválido |
AuthenticationError | 401 | Não | Chave de API ausente ou inválida |
PermissionDeniedError | 403 | Não | Chave de API não tem acesso ao modelo ou recurso solicitado |
NotFoundError | 404 | Não | ID de modelo ou endpoint inválido |
UnprocessableEntityError | 422 | Não | Requisição é JSON bem formado, mas semanticamente inválido |
RateLimitError | 429 | Sim (já retentado automaticamente) | Excedeu requisições por minuto, tokens por minuto ou tokens por dia |
InternalServerError | 5xx | Sim (já retentado automaticamente) | Problema transitório no serviço Anthropic |
APIConnectionError | (sem resposta) | Sim (já retentado automaticamente) | Falha de DNS, conexão recusada, interrupção de rede antes de qualquer resposta |
APIStatusError | qualquer não-2xx | Depende - classe base | Captura genérica para qualquer erro HTTP não correspondido por uma subclasse mais específica acima |
APIError | (qualquer) | Depende - classe base | Raiz de toda a hierarquia de exceções; captura mais ampla possível |
Ordem de Captura (Mais Específica Primeiro)
import anthropic
try:
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Olá"}],
)
except anthropic.NotFoundError:
# ID de modelo ou endpoint incorreto - corrija a requisição, não retente
...
except anthropic.RateLimitError:
# Esgotou as próprias retentativas do SDK; espere mais ou reduza a taxa de requisições
...
except anthropic.APIStatusError as e:
# Qualquer outra resposta HTTP não-2xx
print(e.status_code, e.message)
except anthropic.APIConnectionError:
# Falha de rede antes de qualquer resposta ser recebida
...APIConnectionError é um irmão de APIStatusError em Python (não uma subclasse), então precisa de sua própria cláusula except; ele não será capturado por um ramo except anthropic.APIStatusError.
O Que o SDK Já Retenta Automaticamente
| Falha | Retentado automaticamente por padrão? | Seu código precisa... |
|---|---|---|
APIConnectionError (falha de rede) | Sim, até max_retries (padrão 2) | Lidar apenas se as retentativas forem esgotadas |
429 (RateLimitError) | Sim, respeitando retry-after | Lidar apenas se as retentativas forem esgotadas; considere um backoff mais longo |
5xx (InternalServerError) | Sim | Lidar apenas se as retentativas forem esgotadas |
408, 409 | Sim | Lidar apenas se as retentativas forem esgotadas |
400, 401, 403, 404, 422 | Não | Corrigir a requisição ou credenciais; retentar sem alterações falhará novamente |
Estratégias de Tratamento Seguras para Retentativa
| Exceção | Estratégia Recomendada |
|---|---|
RateLimitError (após retentativas esgotadas) | Faça um backoff significativamente mais longo do que a janela de retentativa padrão do SDK, ou descarregue a carga; considere um limitador de taxa de bucket de tokens no lado do cliente |
APIConnectionError (após retentativas esgotadas) | Apresente um estado de "serviço inacessível" ao usuário; verifique sua própria rede/DNS antes de assumir que a Anthropic está fora do ar |
InternalServerError (após retentativas esgotadas) | Verifique status.anthropic.com; se persistente, trate como uma interrupção em vez de um bug de código |
AuthenticationError | Nunca retente; verifique se ANTHROPIC_API_KEY está definida e é válida, então falhe ruidosamente - um loop de retentativa silencioso contra uma chave inválida apenas desperdiça tempo |
BadRequestError | Nunca retente sem alterações; registre o payload da requisição (redigindo segredos) e corrija o campo malformado |
PermissionDeniedError | Nunca retente; a chave de API precisa de permissões diferentes ou uma concessão de acesso a modelo diferente |
NotFoundError | Nunca retente; quase sempre um ID de modelo digitado incorretamente - verifique contra o catálogo de modelos atual |
Usando .type para Classificação Mais Detalhada
Cada subclasse de APIStatusError expõe uma string .type correspondente à taxonomia de erros da própria API, útil quando um único status HTTP cobre mais de uma causa subjacente:
except anthropic.APIStatusError as e:
if e.type == "rate_limit_error":
...
elif e.type == "overloaded_error":
...
elif e.type == "invalid_request_error":
...FAQs
Preciso escrever meu próprio loop de retentativa para RateLimitError?
Não para o caso comum.
O SDK já retenta 429s automaticamente até max_retries vezes com backoff; escreva seu próprio tratamento apenas para o que acontece após as retentativas serem esgotadas.
Por que APIConnectionError não é uma subclasse de APIStatusError?
Porque representa uma falha que ocorreu antes de qualquer resposta HTTP ser recebida (um erro de rede), enquanto APIStatusError e suas subclasses representam uma resposta que retornou com um status não-2xx. Elas precisam de cláusulas except separadas.
Qual a diferença entre capturar APIStatusError e APIError?
APIError é a raiz de toda a hierarquia, incluindo APIConnectionError. APIStatusError cobre apenas respostas que realmente chegaram até você com um código de status HTTP. Capturar APIStatusError especificamente exclui falhas no nível de conexão.
AuthenticationError deve ser retentado alguma vez?
Não.
Uma chave de API inválida ou ausente não se torna válida por retentativa; corrija a credencial e falhe rapidamente em vez de entrar em loop.
O que UnprocessableEntityError significa na prática?
A requisição era um JSON válido com a forma correta, mas a API rejeitou seu conteúdo por um motivo semântico - por exemplo, um valor budget_tokens que não satisfaz as restrições da API para esse campo.
Como diferencio rate_limit_error de overloaded_error se ambos podem aparecer como exceções diferentes?
RateLimitError mapeia especificamente para HTTP 429, enquanto overloaded_error (um 529) é tipicamente capturado como APIStatusError - verifique e.type == "overloaded_error" dentro desse ramo para distingui-lo.
Qual é o erro mais comum ao capturar essas exceções?
Escrever um único except anthropic.APIError: amplo (ou capturar Exception simples) que trata todas as falhas de forma idêntica, perdendo a distinção entre erros retentáveis e não retentáveis. Capture a classe mais específica que você se importa primeiro.
O cliente async (AsyncAnthropic) levanta os mesmos tipos de exceção?
Sim.
A hierarquia de exceções é idêntica entre Anthropic() e AsyncAnthropic() - apenas a convenção de chamada (await) difere.
Um 404 é sempre um ID de modelo incorreto?
É a causa mais comum, mas qualquer caminho de endpoint inválido (improvável se você estiver usando apenas os próprios métodos do SDK) também produziria um 404. Verifique a string exata do ID do modelo contra o catálogo atual primeiro.
O que devo registrar ao capturar um APIStatusError?
No mínimo, e.status_code, e.message e e.type. Evite registrar o corpo completo da requisição sem redigir se ele puder conter conteúdo sensível do usuário.
Relacionados
- Noções Básicas do SDK Python - uma primeira olhada na captura de exceções tipadas
- Referência de Configuração de Retentativa e Tempo Limite do SDK Python - o que
max_retriesrealmente retenta antes que essas exceções apareçam - O Modelo Mental do SDK Python da Anthropic - como retentativas e erros se encaixam no design geral do SDK
- Melhores Práticas do SDK Python - tratamento de erros como parte de uma lista de verificação mais ampla
Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (último lançamento 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.