Primeiros passosErros

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ódigoStatusQuando acontece
invalid_api_key401A chave de API está ausente, malformada, é desconhecida, foi revogada ou expirou. A mensagem de uma chave expirada informa a data de expiração.
account_suspended403A conta está suspensa. Todas as chaves dela são recusadas até o fim da suspensão; entre em contato com o suporte.
account_banned403A conta foi banida. As chaves dela são revogadas e o crédito restante é perdido.
card_network_blocked403Recarga com cartão recusada: a requisição veio de uma VPN, da rede Tor ou de uma rede de datacenter.
card_account_risk403Recarga 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_found404O ID em model não é de um modelo ativado. Liste os IDs com GET /v1/models.
unsupported_content400A 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_violation400A requisição foi bloqueada pela verificação de segurança automática.
stateless_only400Uma requisição a /v1/responses definiu previous_response_id ou background: true. Em vez disso, envie a conversa completa em input, sem background.
invalid_request400O 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_balance402Seu 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_reached402A 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_exceeded429Requisiçõ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_exhausted429Todas 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_unavailable503O 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_unavailable503A 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_unavailable503Recarga com cartão recusada porque a verificação de rede está brevemente indisponível; tente novamente ou pague com cripto.
upstream_error502O 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:

json
{
  "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:

json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required."
  }
}

Tipos de erro por status

Statuserror.type da OpenAIerror.type da Anthropic
400invalid_request_errorinvalid_request_error
401authentication_errorauthentication_error
402insufficient_quotabilling_error
403permission_errorpermission_error
404not_found_errornot_found_error
408invalid_request_errorinvalid_request_error
413invalid_request_errorrequest_too_large
429rate_limit_errorrate_limit_error
500, 502, 503api_errorapi_error

Cabeçalhos

  • x-request-id está em toda resposta, inclusive nas de erro. Informe-o quando entrar em contato com o suporte.
  • Retry-After (em segundos) acompanha capacity_exhausted, model_unavailable (os segundos até verificarmos o modelo novamente, no máximo 15), o rate_limit_exceeded do limite por minuto e do limite de contas de teste por rede, e um 503 upstream_error (uma breve interrupção ou reinicialização do nosso lado).

Quando tentar novamente

ErroO que fazer
capacity_exhaustedAguarde 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_unavailableAguarde 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_exceededPara 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_unavailableTente 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_errorCom 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_reachedAdicione crédito, ou aumente o teto ou espere o período dele terminar. Tentar novamente antes disso não adianta.
Outros 4xxCorrija 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.