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.

• 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 este tipo de erro. Para evitar erros 529, 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 erros não seguiria esses mecanismos padrão.

​

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. Por exemplo:

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

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:

import anthropic

client = anthropic.Anthropic()

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

​

Solicitações longas

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 da 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 API de Mensagens não-streaming não devem exceder um timeout de 10 minutos e também definirão uma opção de socket para TCP keep-alive.