Erros da API do Claude



Erros HTTP

A API segue um formato previsível de códigos de erro HTTP:

• 400 - invalid_request_error: Houve um problema com o formato ou conteúdo da sua requisição. Este tipo de erro também pode ser usado para outros códigos de status 4XX não listados nesta seção.

• 401 - authentication_error: Há um problema com sua chave de API (por exemplo, ela está malformada, revogada ou expirada; consulte Expiração de chaves). No Claude Platform na AWS, isso também pode indicar um problema com suas credenciais AWS ou assinatura SigV4.

• 402 - billing_error: Há um problema com suas informações de cobrança ou pagamento. Verifique seus dados de pagamento no Claude Console, ou no AWS Marketplace se você estiver usando o Claude Platform na AWS.

• 403 - permission_error: Sua chave de API não tem permissão para usar o recurso especificado. Verifique as configurações de acesso e de workspace da sua organização no Claude Console.

• 404 - not_found_error: O recurso solicitado não foi encontrado. Verifique o caminho do endpoint e quaisquer IDs de recursos na URL da requisição.

• 409 - conflict_error: A requisição entra em conflito com o estado atual de um recurso. Por exemplo, o recurso foi modificado simultaneamente, ou um valor que deve ser único já está em uso. Resolva o conflito e, em seguida, tente a requisição novamente.

• 413 - request_too_large: A requisição excede o número máximo permitido de bytes. Consulte Limites de tamanho de requisição para os máximos por endpoint.

• 429 - rate_limit_error: Sua conta atingiu um "rate limit" (limite de taxa).

• 500 - api_error: Ocorreu um erro inesperado interno aos sistemas da Anthropic. Tente a requisição novamente com "exponential backoff" (recuo exponencial); se o erro persistir, entre em contato com o suporte informando o ID da requisição.

• 504 - timeout_error: A requisição expirou durante o processamento. Considere usar a API de Messages com streaming para requisições de longa duração. Consulte Requisições longas para mais opções.

• 529 - overloaded_error: A API está temporariamente sobrecarregada.

  

  Erros 529 podem ocorrer quando a API enfrenta alto tráfego entre todos os usuários.

  Em casos raros, se sua organização tiver um aumento acentuado de uso, você poderá ver erros 429 devido a limites de aceleração na API. Para evitar atingir limites de aceleração, aumente seu tráfego gradualmente e mantenha padrões de uso consistentes.

Os SDKs oficiais tentam novamente de forma automática falhas transitórias (como erros de conexão, limites de taxa e erros de servidor 5xx) com recuo exponencial, duas vezes por padrão, respeitando o cabeçalho retry-after quando presente. Cada cliente de SDK aceita uma opção de número máximo de tentativas para configurar ou desabilitar esse comportamento.

Ao receber uma resposta com streaming por meio de "server-sent events" (eventos enviados pelo servidor), ou SSE, um erro pode ocorrer depois que a API retorna uma resposta 200. Nesse caso, o tratamento de erros não segue esses mecanismos padrão. Consulte Eventos de erro para o formato de erros no meio do stream.



Limites de tamanho de requisição

A API impõe limites de tamanho de requisição:

Se você exceder esses limites, receberá um erro 413 request_too_large. Na API do Claude direta, o Cloudflare retorna esse erro antes que a requisição chegue aos servidores da API.



Formatos de erro

A API sempre retorna erros como JSON, com um objeto error de nível superior que sempre inclui um valor type e message. A resposta também inclui um campo request_id para facilitar o rastreamento e a depuração. Por exemplo:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

De acordo com a política de versionamento, os valores dentro desses objetos podem se expandir, e é possível que os valores de type cresçam ao longo do tempo.



Tipos de erro dos SDKs

Os SDKs oficiais lançam exceções tipadas para esses erros em vez de retornar JSON bruto, e os nomes de classes e namespaces diferem por linguagem. Por exemplo, um 404 aparece como anthropic.NotFoundError em Python, Anthropic::Errors::NotFoundError em Ruby, com.anthropic.errors.NotFoundException em Java, e como um único valor *anthropic.Error (ramifique com base em StatusCode) em Go. Capture as classes tipadas do SDK em vez de fazer correspondência de strings nas mensagens de erro, tratando primeiro as classes mais específicas. Cada página de SDK documenta sua hierarquia completa de exceções:

• Python · TypeScript · C# · Go · Java · PHP · Ruby



ID da requisição

Toda resposta da API inclui um cabeçalho request-id único. Esse cabeçalho contém um valor como req_018EeWyXxfu5pfWkrYcMdjWG. O mesmo identificador aparece como o campo request_id nos corpos de resposta de erro. Ao entrar em contato com o suporte sobre uma requisição específica, inclua esse ID para ajudar a resolver seu problema rapidamente.

No Claude Platform na AWS, as respostas incluem dois IDs de requisição: o ID de requisição da AWS (x-amzn-requestid, primário, indexado no CloudTrail) e o ID de requisição da Anthropic (request-id, secundário). Use o ID de requisição da AWS para consultas no CloudTrail e o ID de requisição da Anthropic para tickets de suporte da Anthropic.

Os SDKs de Python e TypeScript expõem o ID da requisição como uma propriedade _request_id nos objetos de resposta de nível superior. Os SDKs de C#, Go, Java e PHP o expõem por meio de seus acessadores de resposta bruta, que também permitem ler qualquer outro cabeçalho de resposta. No Claude Platform na AWS, use o acessador de resposta bruta para ler também o ID de requisição da AWS (x-amzn-requestid):

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

Para exemplos de ID de requisição do Claude Platform na AWS em outras linguagens, consulte IDs de requisição.



Requisições longas

Evite definir um valor grande de max_tokens sem usar a API de Messages com streaming ou a API de Message Batches:

• Algumas redes podem derrubar conexões ociosas após um período variável de tempo, o que pode fazer com que a requisição falhe ou expire sem receber uma resposta da Anthropic.
• As redes diferem em confiabilidade. A API de Message Batches pode ajudá-lo a gerenciar o risco de problemas de rede, permitindo que você consulte os resultados por polling em vez de exigir uma conexão de rede ininterrupta.

Se você estiver construindo uma integração direta com a API, definir um TCP socket keep-alive pode reduzir o impacto de timeouts de conexão ociosa em algumas redes.

Os SDKs validam que suas requisições à API de Messages sem streaming não devem exceder um timeout de 10 minutos. Eles também definem uma opção de socket para TCP keep-alive.

Se você não precisar processar eventos de forma incremental, os SDKs podem consumir o stream por você e retornar o objeto Message completo, idêntico ao que uma chamada sem streaming retorna:

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-sonnet-5",
) as stream:
    message = stream.get_final_message()

print(next(block.text for block in message.content if block.type == "text"))

Consulte Streaming de Messages para mais detalhes.



Erros de validação comuns



Prefill não suportado

Os modelos Claude 4.6 e posteriores e o Claude Mythos Preview não suportam o preenchimento prévio (prefill) de mensagens do assistente. Enviar uma requisição com uma última mensagem do assistente pré-preenchida para qualquer um desses modelos retorna um erro 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "This model does not support assistant message prefill. The conversation must end with a user message."
  }
}

Em vez disso, use saídas estruturadas em modelos que as suportam, instruções no prompt do sistema ou output_config.format.



Blocos de pensamento não podem ser modificados

Se a mensagem mais recente do assistente contiver blocos thinking ou redacted_thinking que foram editados, reordenados, filtrados ou reconstruídos antes de serem enviados de volta à API, a requisição retorna um erro 400 invalid_request_error. A mensagem de erro começa com a posição do bloco problemático (por exemplo, messages.1.content.0) e contém:

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.

Com uso de ferramentas, todo bloco thinking e redacted_thinking do turno do assistente deve ser passado de volta exatamente como recebido, incluindo blocos cujo campo thinking está vazio. Passe os blocos de pensamento de volta sem alterações e, se sua aplicação filtrar blocos de conteúdo por tipo antes de reenviar, inclua tanto thinking quanto redacted_thinking. Consulte Solução de problemas de pensamento, Preservando blocos de pensamento e Saída de pensamento no Claude Fable 5 e Claude Mythos 5.



Pensamento estendido não suportado

Os modelos Claude 4.7 e posteriores removeram o "extended thinking" (pensamento estendido). Enviar thinking: {"type": "enabled"} para qualquer um desses modelos retorna um erro 400 invalid_request_error:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Em vez disso, use o pensamento adaptativo. Migrando para o pensamento adaptativo mostra o mapeamento de parâmetros, e Solução de problemas de pensamento cobre a correção a partir do sintoma.



Pensamento adaptativo não suportado

Modelos que suportam apenas pensamento estendido (modelos Claude 4.5 e anteriores) rejeitam thinking: {"type": "adaptive"} com um erro 400 invalid_request_error:

adaptive thinking is not supported on this model

Use thinking: {"type": "enabled", "budget_tokens": N} nesses modelos; consulte Pensamento estendido para a configuração e Solução de problemas de pensamento para a correção a partir do sintoma.



O pensamento não pode ser desabilitado

No Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, o pensamento está sempre ativado. Enviar thinking: {"type": "disabled"} para qualquer um desses modelos retorna um erro 400 invalid_request_error:

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

No Claude Fable 5 e Claude Mythos 5, a própria sugestão da mensagem de erro de "thinking.type.enabled" também é rejeitada. Omita o parâmetro thinking e a requisição será executada com pensamento adaptativo. Para manter o conteúdo de pensamento fora das respostas sem desativar o pensamento, defina display: "omitted" na configuração de pensamento. Consulte Solução de problemas de pensamento.



Federação de identidade web de saída desabilitada (Claude Platform na AWS)

Se toda requisição ao Claude Platform na AWS retornar "Outbound web identity federation is disabled for your account", execute aws iam enable-outbound-web-identity-federation uma vez por conta AWS. Consulte Habilitar federação de identidade web de saída para detalhes.



Próximos passos