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 uma organização ou um workspace. A exceção são os limites no workspace do Claude Code, que podem retornar um 429.

• 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 on AWS, isso também pode indicar um problema com suas credenciais da AWS ou com sua assinatura SigV4.

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

• 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 os 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 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 ver os máximos por endpoint.

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

• 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 ID da solicitação.

• 504 - timeout_error: O tempo limite da solicitação foi atingido 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.

Os SDKs oficiais repetem automaticamente as falhas transitórias (como erros de conexão, limites de taxa e erros de servidor 5xx) com recuo exponencial. Por padrão, fazem duas novas tentativas e respeitam o cabeçalho retry-after quando ele está presente. O cliente do SDK aceita max_retries para configurar ou desativar esse comportamento.

Ao receber uma resposta em streaming por "server-sent events" (eventos enviados pelo servidor), ou SSE, um erro pode ocorrer depois que a API já retornou uma resposta 200. Nesse caso, o tratamento de erros não segue esses mecanismos padrão. Consulte Eventos de erro para ver o formato dos erros que ocorrem 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 dos SDKs

Os SDKs oficiais lançam exceções tipadas para esses erros em vez de retornar o JSON bruto. Os nomes das classes e os namespaces variam conforme a linguagem. Por exemplo, um 404 aparece como anthropic.NotFoundError. O SDK de Go usa um único tipo de erro para todos os status, *anthropic.Error; para diferenciá-los, verifique StatusCode. 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 de cada SDK documenta sua 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 variável, o que pode fazer a solicitação falhar ou atingir o tempo limite sem receber uma resposta da Anthropic.
• As redes variam em confiabilidade. A Message Batches API pode ajudar você a gerenciar o risco de problemas de rede, pois permite consultar os resultados periodicamente em vez de exigir uma conexão de rede ininterrupta.

Se você estiver criando uma integração direta com a API, configurar 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 verificam se as 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 o keep-alive TCP.

Se você não precisar processar os 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 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 a qualquer um desses modelos uma solicitação cuja última mensagem do assistente esteja preenchida previamente 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"} a qualquer um desses modelos retorna um 400 invalid_request_error. Em todos esses modelos, exceto no 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. Para a configuração de pensamento mais baixa, use thinking: {"type": "between_tools"}, que desativa o pensamento antecipado. Enviar thinking: {"type": "disabled"} retorna um 400 invalid_request_error com esta mensagem:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

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 seja diferente 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.

Nas duas mensagens, "enable thinking" se refere ao 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 a cada turno, use o pensamento adaptativo.

Enviar thinking: {"type": "between_tools"} a 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 dos erros de between_tools e de esforço, consulte Solução de problemas de pensamento.

Se você omitir o parâmetro thinking, 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

Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e 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": "..."} a qualquer um desses modelos retorna um 400 invalid_request_error, inclusive no endpoint de contagem de tokens:

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 o uso estrito de ferramentas para manter as entradas das ferramentas válidas de acordo com o schema. Se você precisar que a própria resposta tenha um formato JSON fixo, use saídas estruturadas. 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 e o Claude Sonnet 5.5 oferecem suporte ao uso do computador apenas como o toolset computer_toolset_20260801. Nessas plataformas, enviar a qualquer um dos dois modelos uma entrada em 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, depois de Did you mean one of, lista os tipos de ferramenta que o modelo aceita. Para o Claude Opus 5.5, ela começa assim:

'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 suporte. 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 e no Claude Sonnet 5.5, a API só aceita um bloco de pensamento reenviado se o prompt system, as tools e as mensagens que o precederam não tiverem sido alterados. Em contas novas criadas a partir de 31 de agosto de 2026, e em 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 Mantendo 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