Manejo de errores
Maneje los errores API antes de que lleguen a los usuarios.
Cree rutas de recuperación predecibles para errores de autenticación, reglas de uso, límites de velocidad, errores de validación y errores de dependencia.
Última actualización: July 12, 2026. Examples uso safe placeholders y hacer no incluir real clave APIs o customer prompts.
Regla del lado del cliente
Registre suficiente contexto para depurar el error, pero nunca registre API claves sin procesar, secretos, datos de pago ni indicaciones completas del cliente.
mapa de fallas
Comience con la clase de fracaso.
La mayoría de los problemas de integración se clasifican en uno de cinco grupos. Primero clasifique la respuesta y luego elija la siguiente acción.
Errores de autenticación
Confirme el encabezado de autorización, el formato de clave, el estado activo, la caducidad, la lista de direcciones IP permitidas y el alcance del punto final requerido antes de volver a intentarlo.
Cuota superada
Los errores de cuota significan que la solicitud cruzaría un límite de paquete para solicitudes, tokens o imágenes. Reduzca el uso, espere el reinicio o cambie la capacidad del paquete.
Fallos de validación
El JSON no válido, los campos faltantes, los valores no admitidos y las cargas útiles con formato incorrecto deben corregirse en el lado del cliente antes de volver a enviar la misma solicitud.
Fallos de dependencia
Una dependencia interna o una ruta de red pueden fallar después de que se acepte su solicitud. Trate los fallos transitorios 5xx con reintentos limitados y mantenga redactado el contexto de soporte.
Escalada de soporte
Escale fallas repetidas con punto final, marca de tiempo, estado, código de error, entorno, prefijo de clave enmascarada y cualquier ID de solicitud o ID de seguimiento del proveedor cuando el enrutamiento esté habilitado.
Forma de respuesta
Analice el objeto de error compatible con OpenAI.
Check HTTP estado primero, luego branch en error.code para recuperación path.
{
"error": {
"message": "Missing or invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key"
}
}| Estado | Códigos | causa común | Siguiente acción |
|---|---|---|---|
| 400 | invalid_json, invalid_payload | El cuerpo de la solicitud no es válido JSON o no coincide con el esquema del punto final. | Corrija la carga útil y vuelva a enviarla solo después de que pase la validación. |
| 401 | clave_api_inválida | La clave API falta, está mal formada o no se reconoce. | Verifique el token de portador, la variable de entorno y el prefijo de clave. |
| 402 | suscripción_inactiva, suscripción_no disponible | La suscripción adjunta a la clave no puede acceder a API. | Revise el estado de facturación antes de enviar más tráfico al cliente. |
| 403 | clave_api_inactiva, clave_api_expirada, ip_not_allowed, alcance_insuficiente | La clave es conocida pero está bloqueada por estado, vencimiento, política de IP o alcance. | Gire o actualice la clave y luego vuelva a intentarlo con el alcance requerido. |
| 429 | request_quota_exceeded, token_quota_exceeded, image_quota_exceeded, cuota_exceeded | La solicitud excedería la cuota del paquete. | Reduzca el tamaño de la solicitud, espere el período de cuota o elija un paquete más grande. |
| 429 | tasa_limit_excedida | El cliente envía solicitudes más rápido de lo que permite el límite de velocidad local. | Respete el reintento posterior cuando esté presente y utilice el retroceso exponencial. |
| 501 | streaming_not_enabled | La característica solicitada se reconoce pero no se habilita para el punto final. | Deshabilite la opción no compatible o comuníquese con el soporte técnico si la función es necesaria. |
| 5xx | Comprobar el cuerpo de la respuesta | Error en una dependencia interna o ruta de red. | Vuelva a intentar el trabajo idempotente con retroceso y luego intensifique los fallos repetidos con el contexto. |
Reintentar guía
Reintente sólo los fallos que puedan recuperarse.
Los reintentos ayudan con fallas temporales de presión o dependencia. Hacen que los problemas de validación, permisos y facturación sean más ruidosos si nada cambia.
Reintentar con retroceso
429 rate_limit_exceeded, 408, 500, 502, 503, 504
Utilice un retroceso exponencial acotado con fluctuación. Respete el Reintento-Después cuando la respuesta lo incluya.
No volver a intentarlo sin cambios
400, 401, 402, 403, 501
Corrija la solicitud, la clave, el estado de facturación, el permiso o el indicador de función antes de intentar realizar la misma llamada nuevamente.
Reintentar después de cambios de capacidad
429 códigos de cuota
Los errores de cuota generalmente requieren cargas útiles más pequeñas, trabajo retrasado o un cambio de paquete en lugar de reintentos inmediatos.
async function callWithBackoff(runRequest) {
for (let attempt = 0; attempt < 3; attempt += 1) {
const response = await runRequest();
if (response.ok) {
return response;
}
const retryable = [408, 429, 500, 502, 503, 504].includes(response.status);
if (!retryable) {
return response;
}
const retryAfter = Number(response.headers.get("retry-after") ?? 0);
const delayMs = retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
return runRequest();
}Notas de implementación
Mantenga limitados los reintentos para que una acción del usuario no pueda generar un pico de tráfico.
Agregue jitter en clientes de producción que envían tráfico simultáneo.
Muestra un mensaje de usuario útil después del último reintento en lugar de ocultar el error.
Capture diagnósticos redactados antes de que salga el ciclo de reintento.
Escalada
Envíe apoyo al contexto en el que puedan actuar.
Un buen paquete de escalamiento acorta la clasificación sin exponer secretos, indicaciones o datos del cliente.
Contactar con soporteFAQ
Error al manejar las preguntas.
¿Qué forma de error debería esperar mi cliente?
/v1 API devuelve un objeto de error OpenAI compatible con JSON con error.message, error.type y error.code. Los errores de validación también pueden incluir detalles a nivel de campo.
¿Debo volver a intentar cada respuesta 429?
No. Vuelva a intentar respuestas cortas rate_limit_exceeded usando Retry-After cuando esté presente. Para códigos de cuota, reduzca el uso, espere el reinicio o elija un paquete con más capacidad.
¿Qué debo enviar a soporte?
Comparta el punto final, el método, la marca de tiempo, el estado, el código de error, el prefijo de clave enmascarada, el entorno y cualquier ID de solicitud. Incluya ID de seguimiento externos solo cuando el soporte técnico los solicite. No envíe API claves, secretos ni mensajes de cliente sin procesar.
Herramientas gratuitas
Depurar errores con herramientas gratuitas
Busque códigos de error, decodifique respuestas 429, simule reintentos y planifique el monitoreo del límite de velocidad.
Búsqueda de código de error
Busque códigos de error unlimitedcodex, estados HTTP, instrucciones de reintento y acciones de recuperación.
429 Decodificador
Pegue un cuerpo de respuesta 429 y encabezados para clasificar el límite de tasa frente a la presión de cuota y consulte la guía de reintento.
Reintentar simulador
Ajuste la configuración de retroceso y reintento para ver resultados simulados y copie un fragmento del controlador de reintento.
Planificador de límite de tarifa
Planifique la configuración de retroceso y la lista de verificación de monitoreo de cuotas del RPS esperado y el tamaño del equipo.