Guias
Erros
Formato dos erros, códigos de status e quais erros vale a pena repetir.
Os erros seguem o formato do endpoint que você chamou.
Formatos da OpenAI:
{"error": {"message": "not enough credits for this request. Add credits in the console", "type": "insufficient_quota", "code": "insufficient_credits"}}Messages:
{"type": "error", "error": {"type": "rate_limit_error", "message": "too many requests per minute for this key"}}| Status | Código | Repetir? | O que fazer |
|---|---|---|---|
| 400 | invalid_request, unsupported_parameter | Não | Corrija o corpo |
| 401 | invalid_api_key | Não | Confira a chave |
| 402 | insufficient_credits, key_budget_exceeded | Não | Adicione créditos ou aumente o orçamento da chave |
| 403 | key_not_allowed, account_suspended | Não | Confira os modelos da chave ou fale com o suporte |
| 403 | consent_required | Não | Quem criou a chave recusou ou retirou o consentimento para processamento nos Estados Unidos e na China. Essa pessoa pode aceitar no console |
| 404 | model_not_found, not_found | Não | Confira o ID |
| 413 | request_too_large | Não | Envie menos |
| 429 | rate_limit_exceeded, concurrency_limit_exceeded, capacity_busy | Sim | Espere os segundos de retry-after |
| 500 | internal_error | Sim, com backoff | Informe o x-request-id se continuar acontecendo |
| 502, 504 | upstream_error, upstream_timeout | Sim, com backoff | |
| 503 | model_unavailable | Sim | Tente de novo com backoff (retry-after vem definido enquanto o serviço reinicia) ou use outro modelo |
retry-after vem em segundos inteiros, nunca mais de 60. Requisições que falham não são cobradas.
Retentativas seguras
Em requisições sem streaming, envie o cabeçalho Idempotency-Key. Uma nova tentativa com a mesma chave dentro de 24 horas devolve a primeira resposta, com x-notholy-idempotent-replay: true, e não é cobrada de novo.
curl https://api.notholy.com/v1/chat/completions \
-H "Authorization: Bearer $NOTHOLY_API_KEY" \
-H "Idempotency-Key: report-42-summary" \
-H "Content-Type: application/json" \
-d '{"model": "notholy-specter", "messages": [{"role": "user", "content": "One-line summary of an open redirect."}]}'Os SDKs oficiais já repetem 429 e 5xx com backoff.