Erros
Os erros voltam como JSON com status 4xx ou 5xx. O formato segue o protocolo do endpoint; assim, os SDKs da OpenAI e da Anthropic lançam as classes de exceção habituais. Há um caso diferente: depois que uma requisição sem streaming passa 90 segundos em execução, um erro posterior chega no corpo de uma resposta 200 (veja Requisições longas).
Códigos de erro
| Código | Status | Quando acontece |
|---|---|---|
invalid_api_key | 401 | A chave de API está ausente, malformada, é desconhecida, foi revogada ou expirou. A mensagem de uma chave expirada informa a data de expiração. |
account_suspended | 403 | A conta está suspensa. Todas as chaves dela são recusadas até o fim da suspensão; entre em contato com o suporte. |
account_banned | 403 | A conta foi banida. As chaves dela são revogadas e o crédito restante é perdido. |
card_network_blocked | 403 | Recarga com cartão recusada: a requisição veio de uma VPN, da rede Tor ou de uma rede de datacenter. |
card_account_risk | 403 | Recarga com cartão recusada: a análise antifraude da Stripe classificou a conta como de risco máximo, então ela não pode adicionar crédito com cartão. As recargas com cripto continuam funcionando. |
model_not_found | 404 | O ID em model não é de um modelo ativado. Liste os IDs com GET /v1/models. |
unsupported_content | 400 | A requisição contém uma parte que o modelo não aceita: uma parte de imagem ou vídeo para um modelo cujas input_modalities não a incluem; um vídeo que não é uma URL https:// (incluindo vídeo em base64), ou uma URL de imagem que não é https://, http:// nem data:; ou uma parte de áudio ou arquivo, que nenhum modelo aceita. |
content_policy_violation | 400 | A requisição foi bloqueada pela verificação de segurança automática. |
stateless_only | 400 | Uma requisição a /v1/responses definiu previous_response_id ou background: true. Em vez disso, envie a conversa completa em input, sem background. |
invalid_request | 400 | O corpo não passou na validação (por exemplo, max_tokens ausente em /v1/messages; n diferente de 1; mais de 4 prompts em um array prompt de /v1/completions; service_tier: "priority" em um modelo sem nível prioritário; um tipo de ferramenta diferente de function (ou de custom e namespace em /v1/responses); ou /v1/completions com um modelo que não tem endpoint de completions), o corpo não foi recebido a tempo (status 408) ou passa de 16 MiB (status 413), ou o modelo o rejeitou, por exemplo, um prompt maior que a janela de contexto ou mais imagens do que ele aceita. As rejeições do modelo mantêm o próprio status 4xx e a própria mensagem. |
insufficient_balance | 402 | Seu saldo não cobre a entrada estimada mais um orçamento de saída de pelo menos 256 tokens. Adicione crédito. |
key_spend_cap_reached | 402 | A reserva desta requisição, somada ao gasto liquidado da chave e às outras requisições dela em andamento, ultrapassaria o teto de gastos diário, mensal ou total da chave. |
rate_limit_exceeded | 429 | Requisições demais neste minuto para a chave ou para a conta, requisições simultâneas demais para a conta, uma parte grande demais do orçamento de corpos em andamento ocupada pelos uploads grandes da conta, ou, em uma conta de teste, mais de 2 contas de teste enviando requisições da mesma rede em uma hora. Os limites por minuto e o limite de rede para contas de teste enviam Retry-After. |
capacity_exhausted | 429 | Todas as réplicas do modelo continuaram ocupadas durante 30 s de novas tentativas (contas de teste não têm novas tentativas e falham na hora), ou o gateway está brevemente no limite de capacidade ou reiniciando (status 503). Aguarde os segundos indicados em Retry-After. Um modelo sem nenhuma capacidade de atendimento retorna model_unavailable em vez disso. Nada é cobrado. |
model_unavailable | 503 | O modelo está sem capacidade de atendimento no momento, por exemplo, enquanto as GPUs dele são substituídas. A requisição falha na hora, para todas as contas, sem novas tentativas. Retry-After informa os segundos até verificarmos o modelo de novo; tente novamente nesse momento ou use outro modelo. Nada é cobrado. |
safety_unavailable | 503 | A verificação de segurança expirou ou falhou, então a requisição foi recusada em vez de ser enviada sem verificação. Tente novamente em breve. |
card_network_check_unavailable | 503 | Recarga com cartão recusada porque a verificação de rede está brevemente indisponível; tente novamente ou pague com cripto. |
upstream_error | 502 | O backend do modelo falhou, ou a requisição foi interrompida pelo limite de tempo de 10 minutos, após 2 minutos sem saída do modelo ou por uma reinicialização. Uma falha interna inesperada retorna este código com status 500, uma breve interrupção ou uma reinicialização do nosso lado o retorna com status 503 e Retry-After, e uma falha do backend o retorna com status 502, sempre antes de qualquer resposta ser enviada. Os limites de tempo só são atingidos depois: eles encerram um stream, e uma resposta sem streaming ainda em execução após 90 segundos já foi enviada com status 200, então este erro, vindo de um limite de tempo ou de qualquer outra causa, chega no corpo dela sem Retry-After (veja Requisições longas). Se o modelo ainda não tinha gerado nenhuma saída, nada é cobrado; repita a requisição. Depois que ele gerou saída, a requisição é cobrada pela entrada estimada mais a saída gerada antes da falha ou da interrupção. Um cliente que se desconecta nunca recebe este erro; ele é cobrado pela entrada estimada mesmo quando nenhuma saída foi gerada. |
O que content_policy_violation bloqueia está definido na política de uso aceitável.
Formato da OpenAI
Usado por /v1/chat/completions, /v1/responses, /v1/models e /v1/balance. code é um dos códigos acima. Por exemplo:
{
"error": {
"type": "rate_limit_error",
"code": "capacity_exhausted",
"message": "All model replicas are busy. Retry shortly."
}
}Formato da Anthropic
Usado por /v1/messages. Esse formato não tem o campo code; então leia o status HTTP e error.type. Por exemplo:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens is required."
}
}Tipos de erro por status
| Status | error.type da OpenAI | error.type da Anthropic |
|---|---|---|
| 400 | invalid_request_error | invalid_request_error |
| 401 | authentication_error | authentication_error |
| 402 | insufficient_quota | billing_error |
| 403 | permission_error | permission_error |
| 404 | not_found_error | not_found_error |
| 408 | invalid_request_error | invalid_request_error |
| 413 | invalid_request_error | request_too_large |
| 429 | rate_limit_error | rate_limit_error |
| 500, 502, 503 | api_error | api_error |
Cabeçalhos
x-request-idestá em toda resposta, inclusive nas de erro. Informe-o quando entrar em contato com o suporte.Retry-After(em segundos) acompanhacapacity_exhausted,model_unavailable(os segundos até verificarmos o modelo novamente, no máximo 15), orate_limit_exceededdo limite por minuto e do limite de contas de teste por rede, e um 503upstream_error(uma breve interrupção ou reinicialização do nosso lado).
Quando tentar novamente
| Erro | O que fazer |
|---|---|
capacity_exhausted | Aguarde Retry-After segundos e tente novamente. Um 429 significa que as requisições pagas já foram repetidas por até 30 segundos; um 503 significa que o gateway estava no limite da capacidade ou reiniciando e a requisição nunca chegou a um modelo. |
model_unavailable | Aguarde Retry-After segundos e tente novamente: é quando verificamos o modelo de novo. A requisição falhou na hora, sem novas tentativas, porque o modelo não tinha capacidade de atendimento. Uma interrupção como essa pode durar vários minutos; então, se o erro persistir, troque para outro modelo. |
rate_limit_exceeded | Para o limite por minuto, aguarde Retry-After segundos. Para o limite de simultaneidade, tente novamente quando uma das suas requisições em andamento terminar. Para o limite de contas de teste por rede, aguarde Retry-After segundos ou adicione crédito: contas pagas não são limitadas dessa forma. |
safety_unavailable | Tente novamente após alguns segundos. A verificação de segurança é fail-closed: quando não pode ser executada, a requisição é recusada em vez de ser encaminhada sem verificação. |
upstream_error | Com status 503, aguarde Retry-After segundos e tente novamente. Nos outros casos, inclusive em um corpo de 200, tente novamente com backoff exponencial. |
insufficient_balance, key_spend_cap_reached | Adicione crédito, ou aumente o teto ou espere o período dele terminar. Tentar novamente antes disso não adianta. |
| Outros 4xx | Corrija a requisição. Repeti-la sem alterações retorna o mesmo erro. |
Requisições com falha que não produziram saída não são cobradas, inclusive as interrompidas por limite de tempo ou por reinicialização. A única exceção é a desconexão pelo seu cliente, que é cobrada pela entrada estimada mesmo quando nenhuma saída foi gerada. Uma requisição que falha ou é interrompida depois que o modelo gerou saída é cobrada pela entrada estimada mais a saída gerada antes do fim. Veja como uma requisição é cobrada.
Requisições longas
Uma resposta sem streaming é um único objeto JSON, pronto quando o modelo termina. Se ficar pronta em até 90 segundos após a chegada da requisição, ela é enviada normalmente: um resultado ou um erro, com status e cabeçalhos próprios.
Uma resposta que não está pronta após 90 segundos é iniciada nesse momento, para que a conexão continue aberta: o status 200 e Content-Type: application/json são enviados (com x-request-id), e o corpo começa com uma quebra de linha (\n), seguida de outra a cada 15 segundos. Quando o resultado fica pronto, o objeto JSON vem em seguida e a resposta termina. Os parsers JSON ignoram espaços em branco antes de um valor; então os SDKs da OpenAI e da Anthropic, JSON.parse, json.loads e response.json() a leem sem alterações. Dessa forma, uma requisição sem streaming tem o limite de tempo completo de 10 minutos.
Depois que o status é 200, um erro não pode mais alterá-lo. Um erro a partir desse ponto (o limite de tempo de 10 minutos, 2 minutos sem saída do modelo, uma falha no backend ou uma reinicialização) chega no corpo do 200 como o objeto de erro habitual: o formato da OpenAI, ou o formato da Anthropic em /v1/messages. Nenhum cabeçalho Retry-After pode ser enviado com ele. Um cliente que verifica apenas o status não verá o erro; então verifique se o corpo tem um membro error no nível superior. A cobrança é a mesma de qualquer outra requisição com falha ou interrompida (veja acima), e fechar a conexão enquanto espera conta como desconexão do cliente.
O streaming com "stream": true continua sendo uma boa escolha para gerações longas: você vê os primeiros tokens cedo e a saída à medida que é gerada. Ele não é necessário para evitar um timeout.