Erros da Claude API

Erros HTTP

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

• 400 - invalid_request_error: Há um problema com o formato ou o conteúdo da sua solicitação. A API também pode usar esse tipo de erro 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. Limites no workspace do Claude Code são a exceção: eles podem retornar um 429 em vez disso. Se a mensagem indicar um problema com sua solicitação, procure-o em Erros de validação comuns.

• 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.

  Um 401 cuja mensagem começa com CORS requests are not allowed for this Organization não é um problema com sua chave de API. A solicitação incluiu um cabeçalho Origin, que os navegadores adicionam, e sua organização não pode chamar a Claude API diretamente de um navegador. A mensagem continua com because of custom retention settings ou because of its settings. A primeira aparece apenas para acordos de retenção de dados, como “zero data retention” (retenção zero de dados), ou ZDR; a segunda é o caso geral, que inclui a Compliance API. Nenhuma alteração na solicitação do navegador resolve isso, então envie a solicitação a partir do seu próprio “back end” (servidor de back-end); consulte Aplicações baseadas em navegador.

• 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. Um aumento acentuado no uso também pode causar um 429 mesmo enquanto você estiver abaixo dos seus limites de taxa; consulte “Ramp limits” (limites de rampa).

• 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). Se, em vez disso, o tipo de erro for timeout_error, consulte a entrada do 504.

• 504 - timeout_error: A solicitação atingiu o tempo limite durante o processamento. A API também retorna timeout_error com outros códigos de status, como um 500 quando uma solicitação atinge o limite de tempo do servidor antes de a resposta começar. Para solicitações de longa duração da Messages API, use a Messages API com streaming. 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 Claude API primária aplica estes limites de tamanho de solicitação. Para outras plataformas, consulte a visão geral da API.

Se você exceder esses limites, receberá um erro 413 request_too_large. Na Claude API primária, 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 da API, os valores dentro desses objetos podem ser ampliados, e novos valores de type podem aparecer.

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. Esse cabeçalho 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 ID de solicitação da AWS (x-amzn-requestid, principal, indexado no CloudTrail) e o ID de solicitação da Anthropic (request-id, secundário). 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 APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.:

• Algumas redes podem encerrar conexões ociosas após um período de tempo variável, 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 APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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.

O Anthropic SDK valida que suas requisições sem streaming à API Messages não devem exceder um tempo limite de 10 minutos. Ele também define uma opção de socket para TCP keep-alive.

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 Obter a mensagem final sem tratar eventos 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 os blocos de pensamento na solicitação não corresponderem ao que a API retornou, a solicitação pode receber 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), devolva todos os blocos thinking e redacted_thinking do turno do assistente exatamente como recebidos, incluindo blocos cujo campo thinking esteja vazio. Se sua aplicação filtra blocos de conteúdo por tipo antes de reenviar, inclua tanto thinking quanto redacted_thinking. Esta é uma falha diferente da verificação de prefixo, cujo erro diz que um bloco está vinculado a uma conversa diferente. Definir prefix_mismatch_behavior pode não resolvê-la. Consulte a correção para blocos de pensamento modificados em Solução de problemas do pensamento.

Pensamento estendido não suportado

Os modelos Claude 4.7 e posteriores não oferecem suporte a “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 pensamento adaptativo. Para o mapeamento de parâmetros, consulte Migrando para o pensamento adaptativo. Para corrigir o erro a partir do sintoma, consulte Um erro 400 diz que "thinking.type.enabled" não é suportado.

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

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

O pensamento não pode ser desativado

No Claude Fable 5.2, no Claude Mythos 5.2, 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 de erro 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 mostrada anteriormente.

Em ambas as mensagens, “enable thinking” significa pensamento adaptativo: omita o campo thinking ou envie thinking: {"type": "adaptive"}. O Claude Sonnet 5.5 e o Claude Haiku 5.5 também rejeitam "enabled" com um erro 400. Para variar o esforço a cada 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 os erros de between_tools e de esforço em Solução de problemas do pensamento.

Omita o parâmetro thinking e a requisiçã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 a correção para o erro de pensamento desativado em Solução de problemas do pensamento.

Uso forçado de ferramentas não suportado

O Claude Fable 5.2, o Claude Mythos 5.2, 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

O Claude Fable 5.2, o Claude Mythos 5.2, o Claude Opus 5.5, o Claude Sonnet 5.5 e o Claude Haiku 5.5 retornam um erro 400 para qualquer versão da ferramenta de uso do computador que não aceitem. Na Claude API, isso inclui computer_20251124 com seu cabeçalho beta. Eles não aceitam computer_20250124 em nenhuma plataforma. A mensagem invalid_request_error da Claude API indica o tipo rejeitado e, após Did you mean one of, lista os tipos de ferramenta que o modelo aceita. Para o Claude Opus 5.5, a mensagem começa com:

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

A Claude API retorna a mesma mensagem para qualquer tipo de ferramenta definido pela Anthropic que o modelo solicitado não suporte. O Claude Fable 5.2, o Claude Mythos 5.2, o Claude Opus 5.5, o Claude Sonnet 5.5 e o Claude Haiku 5.5 suportam uso do computador por meio do conjunto de ferramentas computer_toolset_20260801. Declare {"type": "computer_toolset_20260801"} sem o cabeçalho beta e atualize seu loop de agente conforme descrito em Migrar de computer_20251124. Para migrar de computer_20250124, consulte Mover o uso do computador para o conjunto de ferramentas no guia de migração do Claude Haiku 5.5.

No Amazon Bedrock, o Claude Fable 5.2, o Claude Mythos 5.2, o Claude Opus 5.5, o Claude Sonnet 5.5 e o Claude Haiku 5.5 também aceitam a ferramenta computer_20251124 com o cabeçalho beta computer-use-2025-11-24. Com a API InvokeModel do Amazon Bedrock, envie computer-use-2025-11-24 no array anthropic_beta do corpo da solicitação, em vez de em um cabeçalho. Para essa API, consulte Claude no Amazon Bedrock (bedrock-runtime). Para os modelos a serem usados com cada versão anterior, consulte Versões anteriores da ferramenta.

Bloco de pensamento vinculado a uma conversa diferente

Este erro 400 invalid_request_error significa que um bloco de pensamento que você enviou de volta falhou na verificação de prefixo. Compare system, tools e as mensagens antes do bloco com o que você enviou quando o modelo o produziu. Para saber quais mudanças importam, consulte O que conta como uma mudança. A mensagem de erro começa com a posição do primeiro bloco que falhou na verificação de prefixo:

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".

Reenviar o mesmo histórico falha da mesma forma. Corrigir o código que fez a edição não ajuda esta conversa se a edição ainda estiver em seu histórico. Para continuar, faça uma das seguintes opções:

• Envie o cabeçalho beta thinking-binding-controls-2026-08-01 e defina thinking.block_binding.prefix_mismatch_behavior como "drop_block", na nova tentativa e em todas as solicitações posteriores nessa conversa. No Claude Sonnet 5.5 e no Claude Haiku 5.5, block_binding funciona apenas com thinking: {"type": "adaptive"}.
• Remova o bloco que o erro menciona e todos os blocos thinking e redacted_thinking depois dele, nessa mensagem e em todas as mensagens posteriores. Tente novamente e deixe os blocos removidos fora das solicitações posteriores.

Para evitar que novas conversas falhem, mantenha o histórico somente com acréscimos (“append-only”). Consulte a correção para uma assinatura de bloco de pensamento inválida em Solução de problemas do 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, ative o pensamento ou remova o campo.

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

Se todas as requisiçõ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 para cada conta da AWS. Consulte Ativar a federação de identidade web de saída para mais detalhes.

Próximos passos