Solução de problemas

A maioria dos problemas aparece como um status HTTP e um code no corpo do erro. Encontre o código abaixo; Erros tem a lista completa. Requisições que falham (qualquer 4xx ou 5xx) nunca são cobradas.

{ "error": { "message": "...", "type": "authentication_error", "code": "invalid_api_key" } }

401 invalid_api_key

A chave está ausente, malformada ou revogada.

• Envie-a como Authorization: Bearer sk-api14-.... Os SDKs da OpenAI fazem isso a partir de apiKey / api_key; com curl, confirme que $API14_API_KEY está realmente definida no shell em que você executa o comando (echo ${API14_API_KEY:0:9} deve imprimir sk-api14-).
• Cuidado com aspas ou quebras de linha sobrando quando a chave vem de um arquivo .env.
• Uma OPENAI_API_KEY esquecida no ambiente pode sobrescrever a chave que você pretendia usar. Passe a chave explicitamente para descartar essa possibilidade.
• Uma chave revogada falha imediatamente. As chaves são exibidas apenas uma vez, então, se você perdeu uma, crie uma nova em Chaves de API e revogue a antiga.

Veja Autenticação.

402 insufficient_balance

Seu saldo em USD é $0 ou (no caso de vídeo) está abaixo do custo estimado do job. As requisições ficam bloqueadas até você adicionar fundos; tentar de novo não ajuda.

• Consulte o saldo com GET /credits ou em Cobrança. Veja Saldo e informações da chave.
• Adicione fundos ou ative a recarga automática. Os planos adicionam uso incluído ao mesmo saldo todo mês. Veja Preços e cobrança.
• Em jobs de longa duração, trate esse código como fatal e pare, em vez de deixar as retentativas do SDK girando.

403 model_not_allowed ou plan_required

• model_not_allowed: a chave tem uma lista de modelos permitidos que não inclui este id de modelo. Edite a lista da chave em Chaves de API ou use uma chave sem lista. Os sufixos de variante contam: confirme que o id exato que você envia está permitido.
• plan_required: seu plano não inclui esta categoria de modelo. Os planos padrão cobrem todas as categorias; confira seu plano na página de preços.

404 model_not_found ou not_found

• model_not_found: o id do modelo é desconhecido, está desativado ou foi removido. Os ids incluem o prefixo do provedor: openai/gpt-5-mini, não gpt-5-mini. Consulte o id exato com GET /models ou GET /models/{id} (não precisa de chave). Veja Ids de modelos e variantes.
• not_found: o caminho não existe, ou o job de vídeo ou o id de geração não é seu. Isso geralmente indica uma base URL errada (veja abaixo). Uma consulta de geração logo depois de uma requisição também pode retornar 404 por alguns segundos, até o registro aparecer.

Base URL errada

A base URL é exatamente:

https://api14.com/api/v1

Erros comuns:

Particularidades de bibliotecas: ruby-openai adiciona v1 por conta própria, então seu uri_base é https://api14.com/api (Ruby); openai-go espera uma barra no final, https://api14.com/api/v1/ (Go).

429 rate_limited

Você excedeu o limite de requisições por minuto da sua chave ou plano (Free 5, Pro 100, Team 3,000, Enterprise 3,000+). A resposta inclui Retry-After: 60.

• Espere o Retry-After e tente de novo com backoff exponencial e jitter. Os SDKs oficiais da OpenAI já fazem isso (duas tentativas por padrão; aumente maxRetries / max_retries).
• Para trabalho em massa, controle o ritmo das requisições em vez de disparar tudo de uma vez e coloque vários itens em uma requisição. Veja Guia: processamento em lote.
• Um 429 também pode vir do provedor upstream, especialmente nas variantes :free. Use fallbacks de modelo ou roteamento de provedores para distribuir a carga.

429 daily_limit_reached

A chave atingiu seu limite diário de gasto em USD. Tentar de novo não ajuda até o próximo dia UTC. Aumente ou remova o limite em Chaves de API se o tráfego for esperado. Garanta que sua lógica de retentativa distingue este código de rate_limited; caso contrário, os jobs continuam tentando em vão. Veja Limites de taxa.

Timeouts

Modelos grandes, modelos de raciocínio e saídas longas podem levar minutos.

• Verifique o timeout do seu cliente. Os SDKs de Node e Python usam 10 minutos por padrão; outros clientes HTTP costumam ter padrões menores.
• Use streaming em gerações longas. Os tokens começam a chegar em segundos, e os timeouts de conexão ociosa em proxies e load balancers deixam de ser um problema. Veja Streaming.
• Defina max_tokens e, para modelos de raciocínio, um esforço de raciocínio menor.
• Se você repassa as requisições por um servidor próprio, os timeouts do proxy dele (por exemplo proxy_read_timeout do nginx, que por padrão é de 60 segundos) também se aplicam.
• Um timeout do seu lado não cancela a geração upstream, que ainda pode ser cobrada. Use a consulta de geração com o id da requisição para conferir.

Streaming que desconecta ou para antes do fim

• Verifique finish_reason no último chunk. "length" significa que max_tokens foi atingido; "error" significa que o provedor falhou no meio do stream, e o chunk traz um objeto error. Tente de novo ou adicione fallbacks.
• Proxies e plataformas serverless às vezes fazem buffer ou cortam respostas SSE. Desative o buffering (X-Accel-Buffering: no no nginx) e verifique a duração máxima de resposta da plataforma.
• Se você interpreta o stream por conta própria, ignore as linhas de comentário que começam com : (keep-alives) e pare em data: [DONE].
• Fechar a conexão antes do fim não cancela a cobrança: o provedor pode concluir a geração mesmo assim.

Erros de CORS e apps no navegador

Nunca coloque uma chave de API em código de navegador ou de app móvel. Qualquer pessoa pode lê-la na página e gastar seu saldo. Chame o api14 a partir do seu próprio backend e exponha ao navegador apenas o seu endpoint:

// server.js (Node / Express)
app.post("/api/chat", async (req, res) => {
  const stream = await client.chat.completions.create({
    model: "openai/gpt-5-mini",
    messages: req.body.messages, // valide e limite esta entrada
    stream: true,
  });
  for await (const chunk of stream) res.write(chunk.choices[0]?.delta?.content ?? "");
  res.end();
});

Um erro de CORS no navegador durante o desenvolvimento geralmente é uma base URL errada (a requisição chegou ao site em vez da API) ou um cabeçalho de requisição personalizado que o preflight da API não permite; mover a chamada para o seu servidor resolve os dois casos.

Problemas de versão do SDK

• Python openai anterior à 1.0 usa openai.ChatCompletion.create e openai.api_base. Atualize com pip install -U openai e use o cliente OpenAI(base_url=..., api_key=...).
• chat.completions.parse ausente: versões mais antigas 1.x/4.x só têm client.beta.chat.completions.parse. Atualize o pacote.
• Erros de parâmetro desconhecido vindos do SDK para campos do gateway (provider, models, reasoning, plugins): passe-os com extra_body em Python, ou com a opção equivalente de corpo extra em outros SDKs. Veja Compatibilidade com o SDK da OpenAI.
• 400 upstream com mensagem do provedor: o parâmetro não é aceito por esse modelo ou provedor. Verifique os supported_parameters do modelo em Modelos ou adicione provider: { "require_parameters": true }.