Guías
Errores
Formato de los errores, códigos de estado y qué errores conviene reintentar.
Los errores usan el formato del endpoint al que llamaste.
Formatos de 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"}}| Estado | Código | ¿Reintentar? | Qué hacer |
|---|---|---|---|
| 400 | invalid_request, unsupported_parameter | No | Corrige el cuerpo |
| 401 | invalid_api_key | No | Revisa la clave |
| 402 | insufficient_credits, key_budget_exceeded | No | Agrega créditos o sube el presupuesto de la clave |
| 403 | key_not_allowed, account_suspended | No | Revisa los modelos de la clave o contacta a soporte |
| 403 | consent_required | No | Quien creó la clave rechazó o retiró el consentimiento para el procesamiento en Estados Unidos y China. Puede aceptarlo en la consola |
| 404 | model_not_found, not_found | No | Revisa el ID |
| 413 | request_too_large | No | Envía menos |
| 429 | rate_limit_exceeded, concurrency_limit_exceeded, capacity_busy | Sí | Espera los segundos de retry-after |
| 500 | internal_error | Sí, con backoff | Reporta el x-request-id si se repite |
| 502, 504 | upstream_error, upstream_timeout | Sí, con backoff | |
| 503 | model_unavailable | Sí | Reintenta con backoff (retry-after viene definido mientras el servicio se reinicia) o usa otro modelo |
retry-after viene en segundos enteros y nunca supera 60. Las solicitudes fallidas no se cobran.
Reintentos seguros
En las solicitudes sin streaming, envía un encabezado Idempotency-Key. Un reintento con la misma clave dentro de las 24 horas devuelve la primera respuesta, con x-notholy-idempotent-replay: true, y no se vuelve a cobrar.
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."}]}'Los SDK oficiales ya reintentan los 429 y 5xx con backoff.