Códigos de erro e solução de problemas

Identificar o que falhou

1. Registre o status HTTP real, método e caminho da requisição. O status HTTP e o código de erro da aplicação descrevem camadas diferentes; não substitua um pelo outro.
2. Leia os campos de erro conforme o protocolo chamado. Respostas nativas, OpenAI, Claude e Gemini não têm todas a mesma estrutura.
3. Em streaming, confira também eventos de erro e estado de conclusão; em tarefas assíncronas, confira o status. HTTP 200 não garante geração bem-sucedida.
4. Use a tabela abaixo para corrigir a requisição ou decidir sobre novas tentativas. message é texto explicativo, não um enum estável; não crie condições com base na redação.

Enumeração de códigos de erro da plataforma

Esta é a enumeração completa dos códigos de erro de aplicação da plataforma. Nomes são rótulos de referência; os valores code nas respostas são números. “HTTP comum” é uma orientação de diagnóstico, não um mapeamento fixo de cada endpoint. Use o status HTTP e o corpo reais. Um code repassado pelo provedor pode não pertencer a esta enumeração.

HTTP 429 sozinho não distingue com segurança limites de taxa e de concorrência. Faça essa distinção apenas quando houver um código numérico explícito. Confira identificadores na lista de modelos; não reescreva valores de model por conta própria.

Ler erros por protocolo

Os exemplos abaixo mostram estruturas comuns geradas pela plataforma, não um formato único garantido para toda falha. Erros de autenticação podem vir de diferentes camadas, e respostas repassadas do provedor podem manter estruturas, códigos string ou tipos próprios. Identifique a estrutura real antes de interpretar. Se não a reconhecer, preserve campos originais e status HTTP em vez de forçar uma conversão.

APIs nativas da plataforma

Normalmente leia error.code e error.message. requestId pode estar ausente.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Alguns erros podem usar code e message no nível superior. Clientes devem tolerar a diferença e não tratar a ausência de um objeto error como prova de sucesso. Respostas de validação também podem não conter código numérico. Trate um código ausente como desconhecido, sem inventá-lo.

APIs compatíveis com OpenAI

Erros comuns da plataforma usam code, message e type no nível superior; não são necessariamente envolvidos em error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type é uma categoria do protocolo; nesta estrutura, code é o código numérico de erro da plataforma. api_error sozinho não determina se é apropriado tentar novamente. Erros repassados do provedor ou de streaming podem conter error aninhado; trate a resposta real do protocolo. Veja Chat Completions e Responses.

APIs compatíveis com Claude

Na estrutura comum, o type superior é error, a categoria específica é error.type e a descrição é error.message. Essa estrutura não inclui um code numérico da plataforma. Não invente um.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

A plataforma gera localmente os tipos de erro Claude abaixo. Não é uma enumeração completa dos tipos de erro do provedor.

Veja Mensagens Claude.

Erros no estilo Gemini

Ao receber uma resposta no estilo Gemini, leia error.code, error.message e error.status. Aqui, status é uma categoria string, não um status HTTP ou de tarefa assíncrona.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Erros gerados pela plataforma nessa estrutura usam valores numéricos da plataforma em code. O mapeamento local da string status está abaixo; não é um enum de todos os status do provedor.

503 tem precedência e usa UNAVAILABLE, não INTERNAL. Respostas do provedor podem usar semânticas diferentes para code e status. Não aplique a tabela de erros da plataforma a todo código numérico Gemini.

Tentar novamente com segurança

Respeite um cabeçalho Retry-After válido quando presente. Não presuma que todo erro o inclua. Repetir automaticamente uma geração não idempotente pode executá-la de novo e gerar cobranças adicionais. Esta página não promete suporte geral a chaves de idempotência; adicionar Idempotency-Key por conta própria não garante deduplicação.

Se já tiver um jobId, consulte essa tarefa antes de criar outra. Sem jobId e com resultado incerto, preserve identificador e horário da requisição para investigação.

Streams e tarefas assíncronas

Requisições SSE

Após o início do SSE, o status HTTP pode continuar 200 enquanto uma falha posterior é informada por evento ou payload de erro no stream. Interprete eventos e dados do protocolo escolhido e verifique a conclusão normal. Em erro ou desconexão inesperada, não trate texto ou imagens parciais como resultado completo bem-sucedido. Nomes e payloads de eventos variam por endpoint. Não confira apenas um campo fixo error nem use “qualquer texto recebido” como condição de sucesso.

Tarefas assíncronas

Uma resposta de criação com data.jobId significa que a requisição foi aceita, não que a geração terminou. Uma resposta HTTP bem-sucedida ao consultar uma tarefa significa que a consulta funcionou. Você ainda deve verificar data.status da tarefa:

• PENDING, CONNECT, PROCESSING: continue consultando conforme a documentação Jobs.
• COMPLETED: leia outputResult.
• FAILED, CANCELLED: pare de consultar e preserve o ID da tarefa e a resposta sanitizada para investigação.

Detalhes da falha podem aparecer em data.outputResult.error. Esse campo é opcional e não é garantido para toda tarefa com falha. Use Jobs apenas quando a resposta de criação retornar explicitamente um jobId. Não aplique consulta de tarefas a endpoints que retornam resultados diretamente por JSON ou SSE.

Diagnósticos para usuários e assistentes de IA

Forneça ao suporte ou a um assistente de IA as informações sanitizadas abaixo. Use unknown para campos ausentes e unknown no status HTTP se nenhuma resposta HTTP foi recebida. Preserve caminhos de campos e tipos originais, como error.code: 10000 (number) ou error.code: "invalid_api_key" (string). Não converta automaticamente um code string em código numérico da plataforma nem invente campos ausentes a partir de message, status HTTP ou nomes de modelos.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Leia requestId no corpo da resposta ou no cabeçalho de resposta X-Request-ID, quando disponível. Mantenha jobId como string para evitar perda de precisão em números longos. Forneça apenas parâmetros mínimos sanitizados. Remova chaves de API, tokens, cookies, cabeçalhos completos de autenticação, dados pessoais, prompts privados e conteúdo de arquivos de entrada. Remova parâmetros de consulta de URL e URLs de entrada/saída com assinaturas ou credenciais de acesso. Não cole registros completos sem revisá-los.

Assistentes de IA devem distinguir campos observados de causas possíveis e identificar informações ausentes. Evidência insuficiente não deve ser tratada como prova de que uma requisição teve sucesso, não foi executada ou não gerou cobrança.