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 on 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 on 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 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 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 on 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 oficiais fornecem o ID de requisição da Anthropic como uma propriedade nos objetos de resposta de nível superior, contendo o valor do cabeçalho request-id. No Claude Platform on AWS, use o acessador de resposta bruta para também ler o ID de requisição 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 on AWS em outras linguagens, consulte IDs de requisição.



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 descartar 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ê faça polling dos resultados em vez de exigir uma conexão de rede ininterrupta.

Se você estiver construindo uma integração direta com a API, esteja 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 erro 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.



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

Se toda requisição ao Claude Platform on 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 mais detalhes.