Erros

Cada superfície reporta os erros no formato que os seus clientes esperam, então não existe um formato de erro único. Esta página lista os formatos, o que cada status quer dizer e o que é seguro tentar de novo.

Os formatos#

Dois detalhes que surpreendem as pessoas:

• Nos endpoints /v1, um 401 sempre usa o formato da OpenAI, inclusive em /v1/messages, cujos outros erros usam o formato da Anthropic.
• Um erro no nível do framework em /v1, como um 429 ou um 404 para uma rota que não existe, só é JSON quando você envia Accept: application/json. Todo SDK oficial envia. Um curl puro recebe uma página HTML.

Códigos de status#

Os campos que identificam uma chamada#

Guarde estes campos quando for relatar um problema:

• X-Request-Id, em toda resposta. Ele identifica a requisição HTTP. Você pode enviar o seu, com até 64 letras, dígitos, - e _, e ele volta inalterado, o que permite seguir uma chamada pelos seus próprios sistemas.
• X-Inference-Request-Id, nos endpoints /v1 e no stream do chat, e o campo de corpo request_id, em POST /api/v1/agent/chat e nos eventos do stream do chat. Eles identificam a chamada ao modelo.

Status de provedor em agent/chat#

Quando todos os modelos da cadeia falham, POST /api/v1/agent/chat responde 503 com Retry-After e retry_after para qualquer falha que vale tentar de novo: um limite de requisições, uma cota esgotada no provedor, um provedor sobrecarregado, uma chave de provedor recusada ou ausente, um erro de servidor, ou um servidor que não pode ser alcançado. Ele faz isso seja qual for o status que o provedor enviou, e detail termina dizendo quando tentar de novo. Um 503 aqui não é o gateway fora do ar, e uma chave de provedor recusada não é a sua chave do gateway. Uma requisição que o provedor rejeita como inválida mantém o status do próprio provedor, em geral 400.

Os endpoints /v1 são diferentes. A recusa de um provedor de nuvem mantém o status dele ali só quando nenhum outro modelo da cadeia pode responder; caso contrário o modelo padrão responde com 200 (veja modelos). /v1/chat/completions mapeia os status dos servidores do próprio operador, como a página dele diz.

Erros que chegam tarde#

Uma resposta em streaming já respondeu 200 quando falha, então os erros dela viajam dentro do stream:

• /v1/chat/completions: data: {"error": {…}}, depois data: [DONE].
• /v1/messages: event: error. Um stream que termina sem message_stop também falhou.
• /v1/responses: response.failed ou response.incomplete como último evento.
• /api/v1/chat: um evento error, depois done.

Em todos os casos o texto que chegou antes da falha era real. Quando um modelo para no meio da resposta (504, read_timeout), os endpoints sem streaming o devolvem em partial, e o chat nativo o salva.

Como tentar de novo direito#

• Espere Retry-After quando ele estiver presente. É um número de segundos.
• Caso contrário, espere de forma exponencialmente crescente com jitter, e desista depois de algumas tentativas.
• Não repita um 4xx que não seja 429.
• Uma chamada repetida sem streaming é uma chamada nova: ela é medida de novo.
• Use um X-Request-Id por operação lógica, e o mesmo nas repetições, para poder distingui-las nos logs.