Diagnostica los fallos de la API de OpenAI con un plan de pruebas acotado y reproducible
Una forma práctica de distinguir errores de autenticación, límites de velocidad, tiempos de espera y respuestas malformadas de OpenAI, y volver a probar sin reintentos ni gastos ilimitados.
Resumen · TL;DR
Una comprobación reproducible de la API de OpenAI debe registrar el estado, el código de error, el tiempo transcurrido y la estructura de la respuesta para cada caso. Usa reintentos acotados solo para fallos transitorios; corrige los errores de autenticación, cuota y solicitud en lugar de volver a intentarlo.
Puntos clave
- Identifica los fallos mediante el estado HTTP y el código de error específico, no solo por el estado.
- Reintenta los errores transitorios de límite de velocidad y del servidor dentro de un número de intentos y un plazo fijos; no trates los errores de autenticación ni los de créditos agotados como si fueran temporales.
- Comprueba la estructura de la respuesta por separado del estado HTTP satisfactorio y del JSON válido.
- Mantén un conjunto pequeño y reproducible de casos, y registra las condiciones necesarias para reproducir cada fallo.
En esta página (6)
Empieza con un diagnóstico acotado
Cuando falla una llamada a la API de OpenAI, primero determina si el problema está en el acceso, el volumen de solicitudes, el tiempo transcurrido o los datos devueltos. Esa distinción indica si debes cambiar las credenciales, reducir el ritmo del tráfico, reintentar o validar el análisis de la respuesta en tu aplicación. Un 429 por sí solo no basta para elegir una solución: puede indicar un límite de velocidad temporal o un límite de gasto o de crédito que otro intento no resolverá.
La guía de códigos de error de OpenAI documenta los códigos de error de la API y los tipos de excepción correspondientes de la biblioteca de Python. Úsala como referencia para interpretar la respuesta que observas: Códigos de error de la API de OpenAI.
Clasifica las cuatro categorías de fallos más comunes
| Síntoma | Qué comprobar primero | Siguiente paso |
|---|---|---|
Error de autenticación 401 | ¿La clave es válida y está activa? ¿Se está usando la organización prevista? | Corrige la clave o la organización. Comprueba los permisos del proyecto y, si corresponde, cualquier lista de IP permitidas. |
Respuesta 429 | Revisa el código de error específico y cualquier encabezado Retry-After. | Reduce el ritmo de las solicitudes si se trata de un límite de velocidad. Si se agotaron los créditos o se alcanzó un límite de gasto o uso, resuelve ese límite antes de reintentar. |
| Tiempo de espera agotado o error de conexión | Distingue entre el tiempo de espera de una solicitud y la imposibilidad de establecer una conexión. Registra el tiempo transcurrido y las condiciones de red. | Si corresponde, vuelve a intentarlo con cautela tras una breve espera; ante errores de conexión, investiga los proxies, los certificados o las reglas del firewall. |
| Respuesta HTTP satisfactoria, resultado inutilizable | Comprueba si el cuerpo se puede analizar y si existen los campos que necesita tu aplicación y tienen los tipos esperados. | Trata la ausencia de un campo o su formato no válido como un fallo de validación de respuesta en la aplicación, no automáticamente como un error de autenticación o de límite de velocidad de la API. |
La guía de OpenAI identifica las credenciales no válidas como un 401 y enumera varias causas distintas para un 429, entre ellas el ritmo de solicitudes, los créditos agotados y los límites de organización o proyecto. Para los límites de velocidad, aconseja respetar Retry-After cuando esté presente. Los errores de facturación, gasto y cuota requieren resolver el límite correspondiente; los reintentos repetidos no restablecen el acceso. La guía también enumera APITimeoutError y APIConnectionError como excepciones distintas de la biblioteca de Python. Fuente: Códigos de error de OpenAI.
Haz que una evaluación pequeña sea reproducible
Usa un conjunto fijo de casos en lugar de enviar continuamente solicitudes improvisadas. Empieza con casos que aíslen una condición cada vez:
- Prueba de referencia: Envía una entrada pequeña y válida, y confirma que esté presente el campo de respuesta esperado.
- Comprobación de autenticación: Ejecuta la misma prueba de referencia con las credenciales del proyecto previsto. No expongas deliberadamente una clave real en registros ni informes de prueba.
- Validación de solicitudes: En una prueba controlada, omite o escribe mal un parámetro obligatorio si tu entorno de pruebas lo permite. Registra el estado y el mensaje resultantes; no des por sentado que todas las solicitudes malformadas fallan de la misma manera.
- Gestión de límites de velocidad: Prueba tu lógica de reintentos con una respuesta
429simulada, incluido un encabezadoRetry-After. Evita generar tráfico real para forzar un límite. - Gestión de tiempos de espera: Simula un tiempo de espera agotado en el cliente o en el entorno de pruebas. Un endpoint de prueba lento o las llamadas repetidas en producción pueden generar carga innecesaria y resultados ambiguos.
- Validación de respuestas: Prueba un cuerpo JSON válido al que le falte un campo obligatorio, un campo de tipo incorrecto y un JSON no válido. Son fallos distintos del analizador o del contrato.
Para cada caso, registra la fecha y hora con su zona horaria, el endpoint o la operación, el modelo, el estado HTTP si está disponible, el tipo y el código de error, el número de intentos, el tiempo transcurrido y un identificador de solicitud o contexto de diagnóstico con los datos sensibles ocultos. Nunca guardes credenciales ni entradas confidenciales en registros compartidos. Si contactas con el soporte de OpenAI por un problema persistente, su guía recomienda compartir el modelo, el error y su código, los datos y encabezados de la solicitud, la fecha y hora con su zona horaria, y otros detalles pertinentes; oculta primero los secretos y los datos sensibles.
Establece un límite estricto para los reintentos
Los reintentos solo son útiles cuando el fallo puede desaparecer por sí solo. Define el número máximo de intentos y el tiempo total que tu aplicación dedicará antes de devolver un fallo. Ante una respuesta de límite de velocidad, respeta Retry-After si se proporciona y mantén un presupuesto de reintentos finito. Para los errores del servidor, la guía recomienda volver a intentarlo tras una breve espera; si los problemas persisten, consulta la página de estado o solicita ayuda. Un 401, una solicitud malformada o una respuesta de créditos agotados no justifican un bucle automático de reintentos.
En Python, la biblioteca oficial distingue excepciones como AuthenticationError, BadRequestError, RateLimitError, APITimeoutError e InternalServerError. Gestiona las clases de excepción disponibles en la versión de la biblioteca que tengas instalada y registra el estado y el código de error cuando estén disponibles. El siguiente ejemplo es ilustrativo: muestra una clasificación, no una configuración probada ni una política de reintentos universal:
from openai import OpenAI
client = OpenAI() # Supply credentials using your approved secret-management method.
try:
response = client.responses.create(
model="YOUR_SUPPORTED_MODEL",
input="Return the word ready."
)
text = response.output_text
if not isinstance(text, str) or not text.strip():
raise ValueError("Response text is missing or empty")
print(text)
except Exception as exc:
# In production, classify known SDK exceptions explicitly and log
# status/code when available. Do not log credentials or sensitive input.
print(type(exc).__name__, str(exc))
Debes sustituir el marcador de posición del modelo por un modelo disponible para tu proyecto. El ejemplo no demuestra que un modelo, parámetro o endpoint de proveedor concretos sean compatibles con tu entorno. Si usas otro proveedor compatible, confirma que la compatibilidad con el endpoint y los parámetros coincida con la configuración de tu cliente antes de dar por sentado que el comportamiento será idéntico.
Distingue las respuestas malformadas de los errores de la API
Un estado HTTP válido no garantiza que tu aplicación haya recibido el contenido que espera. Valida la respuesta en el punto de entrada: comprueba que el análisis se complete correctamente, que existan los campos obligatorios y que los valores tengan tipos utilizables. Registra una descripción breve del fallo de validación —por ejemplo, «falta output_text» o «se esperaba una cadena»— en lugar de volcar contenido sensible de la respuesta.
Si la API devuelve un error estructurado, conserva su estado y código en los datos de diagnóstico. Si la solicitud se completa correctamente, pero tu analizador rechaza el cuerpo, etiquétalo por separado. Así queda claro si hay que investigar el acceso a la API o los límites de velocidad, la construcción de solicitudes, el transporte o las suposiciones de la aplicación.
Conclusión
Una evaluación útil de la API de OpenAI es pequeña, reproducible y acotada: una prueba de referencia, casos de fallo específicos, comprobaciones explícitas de la salida y un límite fijo de reintentos. Registra suficiente contexto para reproducir cada fallo y elige el siguiente paso según el código de error específico, no solo el estado HTTP.
FAQ
¿Debo reintentar todos los errores 429 de OpenAI?
No. Comprueba el código de error específico. Un límite temporal de ritmo de solicitudes puede requerir reducir el ritmo y respetar `Retry-After`; si se agotaron los créditos o se alcanzó un límite de gasto o uso, hay que resolver ese límite antes de reintentar.
¿Cómo distingo un fallo de la API de una respuesta malformada?
Registra el estado HTTP y el código de error de la API por separado de la validación de la aplicación. Una respuesta satisfactoria que no se puede analizar o a la que le falta un campo obligatorio es un problema de validación de respuesta, no necesariamente un error de la API.
¿Qué datos debo recopilar si el fallo persiste?
Registra el modelo, el mensaje y el código de error, el contexto de la solicitud y los encabezados pertinentes, la fecha y hora con su zona horaria, el número de intentos y el tiempo transcurrido. Oculta las claves de API y los datos sensibles antes de compartir registros o detalles de soporte.
¿Cómo puedo probar los límites de velocidad sin afectar a producción?
Prueba el comportamiento de los reintentos con una respuesta 429 simulada, incluido un encabezado `Retry-After` simulado. Evita generar tráfico excesivo deliberadamente en un proyecto de producción para activar los límites de velocidad.
Artículos relacionados
Guides
Diagnóstico de errores de OpenAI API en la extracción con JSON Schema
Flujo práctico para solucionar problemas de autenticación, límites de solicitudes, tiempos de espera y JSON no válido en procesos de extracción estructurada con OpenAI.
Guides
Reseña de GPT-5.6 Sol: ¿quién necesita realmente el modelo insignia de OpenAI frente a DeepSeek y Qwen?
Una reseña práctica de GPT-5.6 Sol que compara el modelo insignia de OpenAI con DeepSeek V4 y Qwen, e incluye precios, integración con la API de OpenAI y quién debería usarlo.
Guides
Control de Costos de API de IA con GPT-5.6 Sol: Guía Práctica para Desarrolladores
Aprende a gestionar eficazmente los costos de la API de OpenAI usando GPT-5.6 Sol a través de OneMux. Descubre desgloses de precios, estrategias de ahorro y comparativas de modelos.
Guides
Por qué Claude Opus 4.7 es el mejor modelo de IA para programar en este momento
Comparativa entre Claude Opus 4.7 y GPT-5.4 para programación: calidad de código, razonamiento y costo. Descubre cómo OneMux te ofrece acceso unificado a ambos a través de la API de OpenAI.