Se algo não funcionar, a forma mais rápida de perceber se o problema está do seu lado ou do nosso é executar o mesmo pedido a partir de uma ferramenta diferente.

Cerca de 9 em cada 10 relatórios de «API com falha» acabam por ser um URL base mal configurado, uma chave de API obsoleta, um nome de modelo errado, ou um corpo de pedido retirado de um tutorial três versões de SDK desatualizado.

Teste rápido de diagnóstico

Copie este comando curl para um terminal. Substitua YOUR_KEY pela sua chave de API proveniente do Dashboard e execute-o. Se obtiver uma conclusão normal, a sua chave de API, a rede e o nosso backend estão todos saudáveis — qualquer problema está no código do cliente ou no ambiente.

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

ℹ️

Teste rápido de diagnóstico: Sem terminal à mão? Cole o mesmo modelo + prompt no Playground a partir do Dashboard — mesmo efeito, sem configuração.

Lista de verificação passo a passo

A sua chave de API é válida?

Abra Dashboard → API Keys e confirme que a chave corresponde ao que o seu código utiliza. Uma armadilha comum é o espaço em branco antes do prefixo "sk-air-" proveniente de copiar e colar.

Sintoma: 401 Unauthorized.

O URL base está correto?

O URL base tem de ser https://api.airforce/v1 — não http, e o sufixo /v1 é obrigatório. Tutoriais anteriores ao caminho v1 da OpenAI por vezes omitem-no.

Sintoma: 404 Not Found, ou curl bloqueia.

O nome do modelo está escrito corretamente?

Os IDs de modelo são sensíveis a maiúsculas/minúsculas. Visite a página Models ou chame GET /v1/models para confirmar o ID exato. Um erro de digitação ou um modelo que foi descontinuado devolve um erro claro em vez de «funcionar mas incorretamente».

Sintoma: 400 unknown_model ou 404 model_not_found.

O corpo do pedido tem o formato correto?

As conclusões de chat utilizam um array messages. As imagens utilizam prompt + n. O TTS de áudio utiliza input + voice. Enviar um corpo com formato de chat para /v1/images/generations devolve 400 — fácil de ignorar ao copiar fragmentos entre documentações.

Sintoma: 400 com o campo problemático indicado no corpo da resposta.

Atingiu um limite de taxa ou quota?

429 = demasiados pedidos neste minuto. 402 = o seu plano ou saldo está esgotado. Ambos são visíveis no Dashboard. Os pedidos do nível gratuito têm limites separados dos pedidos de plano pago, pelo que um modelo pago pode responder sem problemas enquanto um gratuito fica sujeito a limite de taxa.

Sintoma: 429 Too Many Requests ou 402 Payment Required.

O modelo está de facto disponível agora?

Verifique a página Models — as interrupções de fornecedor aparecem como «degraded» ou «major outage». Se um modelo estiver em baixo enquanto outros funcionam, é um problema do lado do fornecedor que contornamos via routing, não um erro do cliente.

Sintoma: um modelo específico devolve 5xx enquanto outros funcionam.

O Que Significam os Códigos de Estado HTTP

Cada resposta de erro contém um código de estado HTTP padrão. Saber o que cada um indica poupa um ticket.


400	Do seu lado	Bad Request — JSON malformado, campo obrigatório em falta, parâmetro desconhecido. Corrija o corpo do pedido.
401	Do seu lado	Unauthorized — chave de API em falta ou inválida. Verifique se o cabeçalho Authorization inclui o prefixo "Bearer ".
402	Do seu lado	Payment Required — plano esgotado ou saldo Pay-as-you-go vazio. Subscreva ou recarregue.
403	Do seu lado	Forbidden — o seu plano ou permissão por chave não permite este modelo ou endpoint.
404	Do seu lado	Not Found — endpoint ou ID de modelo desconhecido. Verifique o caminho do URL e a ortografia do modelo.
413	Do seu lado	Payload Too Large — a entrada excede a janela de contexto do modelo. Reduza o prompt.
429	Do seu lado	Too Many Requests — limite de taxa excedido (RPM, RPD ou limite diário de tokens). Abrande ou faça upgrade.
500	Do nosso lado	Internal Server Error — um bug do nosso lado. Reporte se persistir mais de um minuto.
502	Do nosso lado	Bad Gateway — backend a reiniciar (fazemos deploy algumas vezes por dia). Aguarde 5–10 segundos e tente novamente.
503	Do nosso lado	Service Unavailable — todos os fornecedores upstream para esse modelo falharam ao mesmo tempo. Reporte se durar mais de alguns minutos.

💡

Regra de Ouro: Códigos 4xx significam que o seu cliente fez algo que o servidor rejeitou. Códigos 5xx significam que falhámos ao processar um pedido válido. O corpo de erro JSON na resposta normalmente indica o campo que acionou a verificação.

Quando é de facto um Bug

Se o teste de diagnóstico com curl acima funcionar mas o mesmo pedido a partir do seu código não funcionar, o problema está no seu cliente (ou na biblioteca que utiliza). Se o próprio teste falhar com um 5xx, ou devolver um 4xx com uma mensagem que não corresponde ao aspeto do seu pedido, vale a pena reportar.

Como Reportar de Forma Eficaz

Abra um ticket de suporte a partir do Dashboard ou publique em #support no Discord. Inclua:

O código de estado HTTP completo e o corpo da resposta (também o cabeçalho de resposta cf-ray, se presente).
Carimbo temporal aproximado em UTC.
Nome do modelo e qual o endpoint que chamou.
Um cURL mínimo que reproduza o problema (mascare a sua chave de API real!).
Se o teste de diagnóstico acima funciona para si com a mesma chave.

ℹ️

Como Reportar de Forma Eficaz: Os tickets que chegam com estes detalhes recebem uma resposta real à primeira tentativa. Os tickets sem eles quase sempre precisam de uma troca de mensagens antes de conseguirmos ajudar.

Pergunte em #support no Discord

Antes de Reportar um Bug