Erros

O envelope de erro

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "type": "invalid_request_error"
  }
}

Este é o mesmo envelope que a própria API da OpenAI usa, pelo que o tratamento de erros escrito para um cliente já compatível com a OpenAI deve continuar a funcionar sem alterações: verifique primeiro o código de estado HTTP, e leia error.message para uma mensagem que valha a pena mostrar a um programador ou registar em log. error.type é uma categoria estável e verificável por máquina, útil para lógica condicional (tentar novamente ou não, pedir uma nova chave de API ou recuar e tentar de novo) sem ter de interpretar a mensagem em texto livre.

Códigos de estado e tipos

Estado	Tipo	Significado
400	invalid_request_error	O próprio pedido está malformado: um model não reconhecido, um array messages em falta ou vazio, uma mensagem com uma função (role) não suportada, ou uma definição de tools malformada. Corrija o pedido; tentar novamente sem alterar nada falhará sempre da mesma forma.
401	authentication_error	O cabeçalho Authorization está em falta, malformado, ou a chave é inválida, expirou, ou foi revogada. Consulte Autenticação.
429	rate_limit_error	Demasiados pedidos numa janela curta com esta chave. Consulte Limites de taxa para o limite e como recuar corretamente.
500	api_error	Um erro inesperado do lado do servidor, sem relação com o seu pedido. Raro; seguro para tentar novamente, idealmente com um pequeno recuo.
503	api_error	O serviço está temporariamente incapaz de concluir o pedido, tipicamente um problema transitório na própria infraestrutura de geração da tAI e não algo errado no seu pedido. Seguro para tentar novamente.

Alguns exemplos

Um modelo desconhecido:

HTTP/1.1 400 Bad Request

{"error": {"message": "Unknown model: 'tai-4.9'. See https://docs.artfical.com/tai/en for the current list.", "type": "invalid_request_error"}}

Uma chave inválida ou expirada:

HTTP/1.1 401 Unauthorized

{"error": {"message": "Invalid API key.", "type": "authentication_error"}}

Um problema transitório do serviço:

HTTP/1.1 503 Service Unavailable

{"error": {"message": "The AI service is temporarily unavailable. Please retry.", "type": "api_error"}}

Erros a meio de um stream

Assim que uma resposta em streaming começa (a ligação está aberta e os chunks começaram a chegar), um erro já não pode ser comunicado como um corpo JSON de erro normal com um estado fora do 2xx, uma vez que o estado HTTP e os cabeçalhos já foram enviados como 200 no início do stream. Em vez disso, uma falha que aconteça a meio do stream é apresentada como um chunk de conteúdo visível (tipicamente um pequeno aviso entre parênteses retos) seguido de um chunk final normal e [DONE], em vez de a ligação simplesmente cair. Consulte Streaming para o formato exato e a razão pela qual o stream tem sempre a garantia de terminar de forma limpa, seja como for.

O que vale a pena tentar novamente

Como regra geral: os erros 400 e 401 descrevem algo errado com o pedido ou com a própria chave, e tentar novamente de forma idêntica falhará sempre de forma idêntica, por isso corrija primeiro o problema subjacente. 429, 500 e 503 são todos seguros para tentar novamente, idealmente com um pequeno atraso e um limite ao número total de tentativas, em vez de tentar novamente num ciclo apertado; consulte Limites de taxa especificamente para saber como recuar corretamente de um 429.