Erros



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. No Claude Platform na AWS, isso também pode indicar um problema com suas credenciais da AWS ou assinatura SigV4.

• 402 - billing_error: Há um problema com suas informações de cobrança ou pagamento. Verifique seus detalhes 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.

• 404 - not_found_error: O recurso solicitado não foi encontrado.

• 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 limite de taxa.

• 500 - api_error: Ocorreu um erro inesperado interno aos sistemas da Anthropic.

• 504 - timeout_error: A requisição atingiu o tempo limite durante o processamento. Considere usar streaming para requisições de longa duração.

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

  

  Erros 529 podem ocorrer quando as APIs enfrentam tráfego elevado entre todos os usuários.

  Em casos raros, se sua organização tiver um aumento acentuado no 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.

Ao receber uma resposta de streaming via SSE, é possível que um erro ocorra após o retorno de uma resposta 200, caso em que o tratamento de erros não seguiria esses mecanismos padrão.



Limites de tamanho de requisição

A API impõe limites de tamanho de requisição para garantir desempenho ideal:

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



Formato dos erros

Os erros são sempre retornados 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 ser expandidos, e é possível que os valores de type aumentem ao longo do tempo.



Tipos de erro do SDK

Os SDKs oficiais lançam exceções tipadas para esses erros em vez de retornar JSON bruto, e os nomes de classe 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 as classes mais específicas primeiro. Cada página de SDK documenta sua hierarquia completa de exceções:

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



Request ID

Toda resposta da API inclui um cabeçalho request-id exclusivo. Esse cabeçalho contém um valor como req_018EeWyXxfu5pfWkrYcMdjWG. 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 request IDs: o request ID da AWS (x-amzn-requestid, primário, indexado no CloudTrail) e o request ID da Anthropic (request-id, secundário). Use o request ID da AWS para consultas no CloudTrail e o request ID da Anthropic para tickets de suporte da Anthropic.

Os SDKs oficiais fornecem o request ID da Anthropic como uma propriedade nos objetos de resposta de nível superior, contendo o valor do cabeçalho request-id. No Claude Platform na AWS, use o acessador de resposta bruta para também ler o request ID da AWS a partir dos cabeçalhos HTTP:

client = anthropic.Anthropic()

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

Para exemplos de request ID do Claude Platform na AWS em outras linguagens, consulte Request IDs.



Requisições longas

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

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

Se você estiver construindo uma integração direta com a API, deve estar ciente de que configurar 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 da Messages API sem streaming não devem exceder um timeout de 10 minutos e também definirão uma opção de socket para TCP keep-alive.

Se você não precisa processar eventos de forma incremental, use .stream() com .get_final_message() (Python) ou .finalMessage() (TypeScript) para obter o objeto Message completo sem escrever código de tratamento de eventos:

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

Consulte Streaming de mensagens para mais detalhes.



Erros de validação comuns



Prefill não suportado

Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6 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 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Prefilling assistant messages is not supported for this model."
  }
}

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



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 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, cada 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 Preservando blocos de pensamento e Saída de pensamento no Claude Fable 5 e Claude Mythos 5.



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 da AWS. Consulte Habilitar federação de identidade web de saída para mais detalhes.