Formato del error
Todos los errores devueltos por la API siguen el envelope OpenAI: un body JSON con un campo `error` que contiene `message`, `type` y opcionalmente `code` y `param`.
Ejemplo de error
{
"error": {
"message": "Incorrect API key provided. You can find your API key in your welcome email.",
"type": "invalid_request_error",
"code": "invalid_api_key",
"param": null
}
}Códigos HTTP
| Código | Significado | Reintentar? |
|---|---|---|
| 400 | Request mal formado: JSON inválido, campo requerido faltante, parámetro fuera de rango | No — corrige el cliente |
| 401 | API key faltante o inválida | No — verifica la key |
| 403 | API key válida pero sin permiso para este recurso o modelo | No — contacta soporte |
| 404 | Modelo o endpoint no existe | No — corrige el `model` o la URL |
| 413 | Payload demasiado grande (audio >25 MB, contexto excesivo) | No — divide la entrada |
| 422 | Validación semántica falló (formato de audio no soportado, dimensiones inválidas) | No — corrige el cliente |
| 429 | Rate limit excedido | Sí, con backoff — ver /docs/api/rate-limits |
| 500 | Error interno del servidor | Sí, con backoff exponencial |
| 502 / 503 | Backend temporalmente no disponible (mantenimiento, GPU fría) | Sí, con backoff |
| 504 | Timeout en upstream (request muy largo) | Sí; considera reducir el contexto |
Tipos de error en `error.type`
| Tipo | Cuándo aparece |
|---|---|
| `invalid_request_error` | Body mal formado, parámetros incompatibles, formato no soportado |
| `authentication_error` | Key faltante o inválida (también 401) |
| `permission_error` | Key sin acceso al modelo o endpoint (403) |
| `rate_limit_error` | Cuota agotada en la ventana actual (429) |
| `api_error` | Error interno; típicamente transitorio (500) |
| `overloaded_error` | Backend saturado; reintenta con backoff (503) |
Estrategia de reintentos
- Solo reintenta sobre 429, 500, 502, 503 y 504. El resto son errores del cliente y no se resuelven con reintentos.
- Backoff exponencial con jitter aleatorio: `min(60, 2^attempt + random())` segundos. Detalle en /docs/api/rate-limits.
- Honra el header `Retry-After` cuando esté presente — la API ya te dice cuánto esperar.
- Después de 5 reintentos consecutivos sin éxito, escala a un alert o registro de fallos en lugar de seguir reintentando indefinidamente.
Cuándo contactar soporte
Para errores recurrentes que no se resuelven con reintentos, contacta a [email protected] incluyendo: timestamp UTC del error, `id` del request si está en headers, código y body del error, y el endpoint llamado. Tiempo de respuesta: <4 h hábiles en Pro, <1 h hábil en Scale, Slack compartido en Enterprise.