Erros

Erros HTTP

Nossa API segue um formato previsível de código de erro HTTP:

• 400 - invalid_request_error: Houve um problema com o formato ou conteúdo da sua solicitação. Também podemos usar este tipo de erro para outros códigos de status 4XX não listados abaixo.

• 401 - authentication_error: Há um problema com sua chave de API.

• 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 solicitação excede o número máximo permitido de bytes. O tamanho máximo da solicitação é 32 MB para endpoints de API padrão.

• 429 - rate_limit_error: Sua conta atingiu um limite de taxa.

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

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

  Erros 529 podem ocorrer quando as APIs da Anthropic experimentam alto tráfego em todos os usuários.

  Em casos raros, se sua organização tiver um aumento acentuado no uso, você pode ver erros 429. Para evitar esses erros 429, 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 possa ocorrer após retornar uma resposta 200, caso em que o tratamento de erro não seguiria esses mecanismos padrão.

Limites de tamanho de solicitação

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

Tipo de Endpoint	Tamanho Máximo da Solicitação
Messages API	32 MB
Token Counting API	32 MB
Batch API	256 MB
Files API	500 MB

Se você exceder esses limites, receberá um erro 413 request_too_large. O erro é retornado do Cloudflare antes que a solicitação chegue aos servidores de API da Anthropic.

Formatos de erro

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 depuração. Por exemplo:

JSON

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

De acordo com nossa política de versionamento, podemos expandir os valores dentro desses objetos, e é possível que os valores type cresçam ao longo do tempo.

ID da solicitação

Toda resposta da API inclui um cabeçalho único request-id. Este cabeçalho contém um valor como req_018EeWyXxfu5pfWkrYcMdjWG. Ao entrar em contato com o suporte sobre uma solicitação específica, inclua este ID para nos ajudar a resolver rapidamente seu problema.

Nossos SDKs oficiais fornecem este valor como uma propriedade em objetos de resposta de nível superior, contendo o valor do cabeçalho request-id:

Python

import anthropic

client = anthropic.Anthropic()

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

Solicitações longas

Encorajamos fortemente o uso da API de Mensagens de streaming ou API de Lotes de Mensagens para solicitações de longa duração, especialmente aquelas com mais de 10 minutos.

Não recomendamos definir valores grandes de max_tokens sem usar nossa API de Mensagens de streaming ou API de Lotes de Mensagens:

• Algumas redes podem descartar conexões inativas após um período variável de tempo, o que pode causar falha na solicitação ou timeout sem receber uma resposta da Anthropic.
• As redes diferem em confiabilidade; nossa API de Lotes de Mensagens pode ajudá-lo a gerenciar o risco de problemas de rede permitindo que você consulte os resultados em vez de exigir uma conexão de rede ininterrupta.

Se você está construindo uma integração direta de API, deve estar ciente de que definir um TCP socket keep-alive pode reduzir o impacto de timeouts de conexão inativa em algumas redes.

Nossos SDKs validarão que suas solicitaçõ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.