Erros da Claude API

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 o conteúdo da sua solicitação. Esse tipo de erro também pode ser usado para outros códigos de status 4XX não listados nesta seção. A API também retorna um 400 quando o uso atinge um limite de gastos definido por você para a organização ou o workspace, exceto limites no workspace do Claude Code, que podem retornar um 429 em vez disso.

• 401 - authentication_error: Há um problema com sua "API key" (chave de API) (por exemplo, ela está malformada, revogada ou expirada; consulte Expiração de chaves). No Claude Platform on AWS, isso também pode indicar um problema com suas credenciais da AWS ou com a 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 on AWS.

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

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

• 409 - conflict_error: A solicitaçã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 solicitação novamente.

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

• 429 - rate_limit_error: Sua organização atingiu um "rate limit" (limite de taxa), atingiu o teto de gastos mensal do seu nível de uso ou atingiu um limite de gastos no workspace do Claude Code. Um 429 por teto de gastos do nível não tem o cabeçalho retry-after e continua falhando até que o acesso seja retomado; consulte Atingindo seu teto de gastos para saber como reconhecê-lo.

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

• 504 - timeout_error: A solicitação atingiu o tempo limite durante o processamento. Considere usar a Messages API com streaming para solicitações de longa duração. Consulte Solicitações longas para mais opções.

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

O SDK oficial repete automaticamente 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. O cliente do SDK aceita max_retries para configurar ou desativar esse comportamento.

Ao receber uma resposta de streaming por "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 dos erros no meio do stream.

Limites de tamanho de solicitação

A API impõe limites de tamanho às solicitações:

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

Formatos de erro

A API sempre retorna erros em JSON, com um objeto error de nível superior que sempre inclui os valores 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 ampliados, e é possível que novos valores de type sejam adicionados ao longo do tempo.

Tipos de erro do SDK

O SDK oficial lança exceções tipadas para esses erros em vez de retornar JSON bruto. Por exemplo, um 404 aparece como anthropic.NotFoundError. O SDK de Go tem um único tipo de erro para todos os status, *anthropic.Error: verifique StatusCode para diferenciá-los. Capture as classes tipadas do SDK em vez de comparar strings das mensagens de erro, tratando primeiro as classes mais específicas. A página do seu SDK documenta a hierarquia completa de exceções:

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

ID da solicitação

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

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

Os SDKs de Python e TypeScript expõem o ID da solicitaçã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 acessores de resposta bruta, e o SDK de Ruby, por meio de middleware. Em todos os SDKs, exceto o de Ruby, use with_raw_response para ler qualquer outro cabeçalho de resposta, como anthropic-organization-id e anthropic-workspace-id. Em Ruby, use o mesmo middleware. No Claude Platform on AWS, use também o acessor de resposta bruta para ler o ID de solicitaçã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 IDs de solicitação do Claude Platform on AWS em outras linguagens, consulte IDs de solicitação.

Solicitações longas

Evite definir um valor alto 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 de tempo variável, o que pode fazer com que a solicitaçã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 criando uma integração direta com a API, definir um "TCP socket keep-alive" (manutenção de conexão do socket TCP) pode reduzir o impacto dos tempos limite de conexões ociosas em algumas redes.

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

Se você não precisa processar eventos incrementalmente, o SDK pode 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 mensagens 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 oferecem suporte a "prefill" (preenchimento prévio) de mensagens do assistente. Enviar uma solicitação com uma última mensagem do assistente preenchida previamente para qualquer um desses modelos retorna um 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 nos modelos que oferecem suporte a elas, instruções no "system prompt" (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 solicitação retornará 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 "tool use" (uso de ferramentas), todos os blocos thinking e redacted_thinking do turno do assistente devem ser enviados de volta exatamente como foram recebidos, inclusive os blocos cujo campo thinking está vazio. Envie os blocos de pensamento de volta sem alterações. Se sua aplicação filtrar os blocos de conteúdo por tipo antes de reenviá-los, inclua tanto thinking quanto redacted_thinking. Consulte Solução de problemas de pensamento, Preservando blocos de pensamento e Pensamento preservado.

Pensamento estendido não suportado

Os modelos Claude 4.7 e posteriores não têm mais "extended thinking" (pensamento estendido). Enviar thinking: {"type": "enabled"} a qualquer um desses modelos retorna um 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 "adaptive thinking" (pensamento adaptativo). Migrando para o pensamento adaptativo mostra o mapeamento dos parâmetros, e Solução de problemas de pensamento apresenta a correção a partir do sintoma.

Pensamento adaptativo não suportado

Os modelos que oferecem suporte apenas ao pensamento estendido (Claude 4.5 e modelos anteriores) rejeitam thinking: {"type": "adaptive"} com um 400 invalid_request_error:

adaptive thinking is not supported on this model

Nesses modelos, use thinking: {"type": "enabled", "budget_tokens": N}. Consulte Pensamento estendido para ver a configuração e Solução de problemas de pensamento para a correção a partir do sintoma.

O pensamento não pode ser desativado

No Claude Fable 5.1, no Claude Mythos 5.1, no Claude Fable 5, no Claude Mythos 5, no Claude Opus 5.5 e no Claude Mythos Preview, o pensamento está sempre ativado. Enviar thinking: {"type": "disabled"} para qualquer um desses modelos retorna um 400 invalid_request_error. Em todos esses modelos, exceto o Claude Mythos Preview, a mensagem diz:

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

No Claude Mythos Preview, o único desses modelos que aceita pensamento estendido, a mensagem diz:

"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 Sonnet 5.5, o pensamento não pode ser definido como disabled. Use thinking: {"type": "between_tools"} para a configuração de pensamento mais baixa, que desativa o pensamento antecipado. Enviar thinking: {"type": "disabled"} retorna um 400 invalid_request_error com esta mensagem:

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

Com esforço xhigh ou max, uma solicitação com between_tools também retorna um 400 invalid_request_error. A mensagem diz que o pensamento está desativado porque between_tools não tem pensamento antecipado:

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

Com between_tools, o esforço não pode mudar no meio da conversa: um output_config.effort por mensagem que difere do nível em vigor retorna um erro 400. O erro indica a posição da mensagem que definiu o novo nível:

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

O Claude Haiku 5.5 aceita thinking: {"type": "disabled"} e o submete aos mesmos dois limites de esforço que se aplicam a between_tools: com esforço xhigh ou max, ou com um output_config.effort por mensagem que difere do nível em vigor, a solicitação retorna um 400 invalid_request_error com a mensagem correspondente acima.

Em ambas as mensagens, "enable thinking" significa pensamento adaptativo: omita o campo thinking ou envie thinking: {"type": "adaptive"}. O Claude Sonnet 5.5 rejeita "enabled" com um erro 400. Para variar o esforço por turno, use o pensamento adaptativo.

Enviar thinking: {"type": "between_tools"} para qualquer modelo que não seja o Claude Sonnet 5.5 retorna um 400 invalid_request_error:

"thinking.type.between_tools" is not supported for this model.

Para as correções, consulte Solução de problemas de pensamento, que aborda os erros de between_tools e de esforço.

Omita o parâmetro thinking e a solicitação será executada com pensamento adaptativo. Para manter o conteúdo do pensamento fora das respostas sem desativar o pensamento, defina display: "omitted" na configuração de pensamento. Consulte Solução de problemas de pensamento.

Uso forçado de ferramentas não suportado

O Claude Opus 5.5, o Claude Sonnet 5.5, o Claude Fable 5.1 e o Claude Mythos 5.1 não oferecem suporte ao uso forçado de ferramentas. Enviar tool_choice: {"type": "any"} ou tool_choice: {"type": "tool", "name": "..."} para qualquer um desses modelos, inclusive no endpoint de contagem de tokens, retorna um 400 invalid_request_error:

tool_choice: type "tool" and "any" are not supported for this model.

tool_choice: {"type": "auto"} (o padrão) e {"type": "none"} são aceitos. Use auto com uso estrito de ferramentas para manter as entradas das ferramentas válidas segundo o schema, ou saídas estruturadas quando você precisar que a própria resposta tenha um formato JSON fixo. Consulte Forçando o uso de ferramentas.

Versão da ferramenta de uso do computador não suportada

Na Claude API e no Google Cloud, o Claude Opus 5.5, o Claude Sonnet 5.5 e o Claude Haiku 5.5 oferecem suporte ao uso do computador apenas como o toolset computer_toolset_20260801. Nessas plataformas, enviar a qualquer um desses modelos uma entrada tools do tipo anterior computer_20251124 (com o cabeçalho beta dessa ferramenta) retorna um 400 invalid_request_error. A mensagem indica o tipo rejeitado e, em seguida, lista os tipos de ferramenta que o modelo aceita após Did you mean one of. Para o Claude Opus 5.5, ela começa com:

'claude-opus-5-5' does not support tool types: computer_20251124.

A API retorna a mesma mensagem para qualquer tipo de ferramenta definido pela Anthropic que o modelo solicitado não suporta. Declare {"type": "computer_toolset_20260801"} sem o cabeçalho beta e atualize o loop do seu agente conforme descrito em Migrar de computer_20251124. Modelos anteriores que oferecem suporte ao toolset continuam aceitando computer_20251124, assim como o Claude Opus 5.5 e o Claude Sonnet 5.5 no Amazon Bedrock.

O bloco de pensamento não corresponde mais à conversa

No Claude Fable 5.1, no Claude Opus 5.5, no Claude Sonnet 5.5 e no Claude Haiku 5.5, a API aceita um bloco de pensamento reenviado apenas enquanto o prompt system, as tools e as mensagens que o precederam permanecerem inalterados. Para novas contas criadas a partir de 31 de agosto de 2026, e para qualquer solicitação que defina thinking.block_binding.prefix_mismatch_behavior como "error", um bloco reenviado cujo histórico anterior foi alterado é rejeitado com um 400 invalid_request_error (com "drop_block", a API descarta o bloco e a solicitação é bem-sucedida). A mensagem começa com a posição do primeiro bloco com falha:

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

Sem o cabeçalho beta thinking-binding-controls-2026-08-01, a mensagem também menciona esse cabeçalho. Mantenha o histórico da conversa apenas com acréscimos, ou envie o cabeçalho beta com prefix_mismatch_behavior: "drop_block" para descartar o bloco e continuar. No Claude Sonnet 5.5, block_binding funciona apenas com thinking: {"type": "adaptive"}. Com between_tools, mantenha o histórico apenas com acréscimos, ou remova os blocos de pensamento a partir do turno editado. Um bloco de um modelo que o modelo de destino não consegue ler é descartado em vez de rejeitado. Consulte Manter o prefixo inalterado e Solução de problemas de pensamento.

Enviar thinking.block_binding sem o cabeçalho beta thinking-binding-controls-2026-08-01 retorna um 400 invalid_request_error cuja mensagem termina com:

block_binding: Extra inputs are not permitted

Adicione o cabeçalho ou remova o campo.

Federação de identidade web de saída desativada (Claude Platform on AWS)

Se todas as solicitações ao Claude Platform on AWS retornarem "Outbound web identity federation is disabled for your account", execute aws iam enable-outbound-web-identity-federation uma vez por conta da AWS. Consulte Ativar a federação de identidade web de saída para mais detalhes.

Próximos passos