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.
Resumen · TL;DR
Cuando falla la extracción estructurada, distingue los errores de transporte y de API de los fallos de validación de la respuesta. Comprueba primero las credenciales y el acceso al proyecto, reintenta solo los errores transitorios y valida el JSON devuelto con tu esquema antes de utilizarlo.
Puntos clave
- Un error 401 apunta a las credenciales, la pertenencia a la organización o la lista de IP permitidas, no a un problema del esquema de salida.
- Ante respuestas 429, revisa el código de error: los límites de solicitudes pueden requerir reintentos espaciados, mientras que el agotamiento de créditos o de los límites de gasto exige un cambio en la cuenta.
- Una respuesta correcta de la API puede contener datos de extracción inutilizables; analiza el JSON y valídalo con tu JSON Schema.
- Establece límites de reintentos y conserva suficientes metadatos de las solicitudes para diagnosticar fallos recurrentes, sin registrar secretos ni texto sensible de origen.
En esta página (7)
Primero, distingue los errores de API de los errores de extracción
Un proceso de extracción estructurada tiene dos puntos de fallo distintos: la solicitud puede fallar antes de que el modelo devuelva una respuesta utilizable, o la respuesta puede llegar y, aun así, no superar las comprobaciones de análisis o del esquema. Trátalos por separado. Reintentar una respuesta mal formada sin revisar el esquema o la respuesta puede desperdiciar solicitudes; reintentar una y otra vez cuando se han agotado los créditos no restablecerá el acceso.
La guía de códigos de error de OpenAI describe los códigos de estado de la API y los tipos de excepciones correspondientes de la biblioteca de Python. Esta distinción resulta especialmente útil en los procesos de extracción: los errores de autenticación y de solicitud requieren corregir la configuración; los errores transitorios de limitación o de servicio pueden justificar reintentos limitados; y la validación del esquema debe realizarse en la aplicación después de recibir una respuesta. Códigos de error de OpenAI API
Comprueba la autenticación antes de modificar el código de extracción
Si recibes un error 401, verifica que la aplicación esté usando la clave de API activa prevista y el contexto de organización correcto. La guía de errores también señala que la pertenencia a la organización y la lista de IP permitidas pueden ser causas. Si las solicitudes funcionan en un entorno, pero fallan en otro, compara la IP de salida y las credenciales disponibles en cada entorno antes de modificar el prompt de extracción.
Si recibes un error 403, comprueba que la solicitud provenga de un país, región o territorio admitido. Cambiar los campos de JSON Schema no resolverá una restricción de permisos o de acceso.
No incluyas credenciales en el control de versiones ni en los registros. Durante la depuración, registra el nombre del entorno y un identificador de clave parcialmente oculto, pero nunca el secreto.
Clasifica las respuestas 429 antes de reintentarlas
Un 429 no siempre significa «vuelve a enviar la misma solicitud más tarde». Revisa el código y el mensaje de error:
- Límite de solicitudes: reduce la concurrencia o espacía las solicitudes. Respeta
Retry-Aftercuando esté presente y aumenta el tráfico gradualmente, en vez de volver de inmediato al ritmo anterior. - Saldo de créditos agotado: añade créditos antes de reanudar las solicitudes.
- Límite de gasto de la organización o del proyecto: revisa el límite de gasto aplicable.
- Límite de uso de la organización: solicita un aumento del límite aprobado o ponte en contacto con soporte.
La guía indica que los errores de facturación o de límites de uso no se solucionan mediante reintentos. Diseña el controlador en función del código de error específico, no solo del tipo general: algunos errores de facturación pueden compartir un tipo general relacionado con las cuotas con otros fallos.
En los lotes de extracción, un límite sencillo de concurrencia suele ser más seguro que procesar todos los documentos a la vez. Reintenta solo las solicitudes que probablemente hayan fallado por una causa transitoria, con un máximo de intentos y una espera creciente entre ellos. No reintentes los errores de validación como si fueran límites de solicitudes.
Gestiona los tiempos de espera y los errores temporales del servicio de forma segura
Un tiempo de espera del cliente significa que este no recibió una respuesta a tiempo; no demuestra que la solicitud no se haya procesado. Para un trabajo de extracción, asigna a cada documento de origen un identificador de trabajo estable y haz que la persistencia de resultados sea idempotente. Si reintentas, evita crear registros duplicados en los sistemas posteriores.
La guía de OpenAI señala que, ante errores 500 del servidor y errores 503 por sobrecarga del modelo, puede ser útil reintentar tras una breve espera; respeta Retry-After cuando esté presente. También enumera excepciones de la biblioteca de Python, como APITimeoutError, InternalServerError y RateLimitError. En cambio, un fallo de conexión puede deberse a la red, al proxy, a los certificados o a la configuración del firewall. No conviene aplicar el mismo comportamiento de reintento a todos estos casos.
Ejemplo ilustrativo en Python: analizar, validar y luego usar
El ejemplo siguiente muestra las comprobaciones que se realizan con una respuesta estructurada. Es ilustrativo, no una configuración probada. Confirma que el modelo, la versión del SDK, el endpoint y los parámetros de salida estructurada que utilices admitan este formato de solicitud. La guía de códigos de error de OpenAI no documenta la compatibilidad de los parámetros de JSON Schema.
import json
from jsonschema import validate, ValidationError
from openai import OpenAI, APIConnectionError, APITimeoutError
from openai import APIStatusError, RateLimitError
client = OpenAI()
schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
"currency": {"type": "string"}
},
"required": ["invoice_number", "total", "currency"],
"additionalProperties": False
}
try:
response = client.responses.create(
model="YOUR_SUPPORTED_MODEL",
input="Extract the invoice number, total, and currency from: ...",
text={
"format": {
"type": "json_schema",
"name": "invoice",
"strict": True,
"schema": schema
}
}
)
data = json.loads(response.output_text)
validate(instance=data, schema=schema)
except (RateLimitError, APITimeoutError, APIConnectionError) as exc:
# Apply a bounded, error-aware retry policy in the job runner.
print(f"Transient or connection failure: {exc}")
except APIStatusError as exc:
# Inspect status and the API error code before deciding what to do.
print(f"API failure: status={exc.status_code}, message={exc}")
except (json.JSONDecodeError, ValidationError) as exc:
# Quarantine the result; do not pass invalid data downstream.
print(f"Response failed JSON parsing or schema validation: {exc}")
Si el endpoint o el modelo seleccionados no admiten este parámetro de formato de esquema, la solicitud podría fallar por estar mal formada o no ser compatible. Consulta la documentación actual del endpoint en lugar de eliminar la validación sin más. Aunque se disponga de salida restringida, analizar y validar los datos en la aplicación ofrece un límite de seguridad útil antes de que lleguen a una base de datos o a un proceso empresarial.
Lista breve de comprobación para el diagnóstico
- ¿No hay respuesta o se produce una excepción del cliente? Comprueba la conectividad, los tiempos de espera, el proxy y la configuración de TLS.
- ¿Aparece un error 401 o 403? Comprueba la clave, el acceso a la organización, la lista de IP permitidas y la disponibilidad regional.
- ¿Aparece un error 429? Revisa el código exacto. Espacia los reintentos de los errores transitorios por límite de solicitudes; resuelve los problemas de créditos o límites cuando se trate de restricciones de la cuenta.
- ¿Aparece un error 500 o 503? Reintenta con una política limitada y respeta
Retry-Aftercuando se indique. - ¿Se recibió una respuesta, pero no es utilizable? Guarda la respuesta de forma segura, determina si falló el análisis del JSON o la validación del esquema y evita que los registros no válidos pasen a los procesos posteriores.
- ¿El problema persiste? Conserva el nombre del modelo, el código y el mensaje de error, la fecha y hora con su zona horaria, y los detalles y encabezados pertinentes de la solicitud. Oculta las claves de API y el contenido sensible de origen antes de compartir los datos de diagnóstico.
Conclusión
Para lograr una extracción JSON fiable, diagnostica primero el error HTTP o del SDK y luego valida por separado las respuestas correctas. Reintenta solo los errores que puedan resolverse y utiliza el código de error específico para distinguir la limitación de solicitudes de los problemas de créditos, límites de gasto y otras restricciones de acceso.
FAQ
¿Debo reintentar todas las respuestas 429 de OpenAI?
No. Espacia y reintenta los errores por límite de solicitudes dentro de los límites establecidos, respetando `Retry-After` cuando esté presente. El agotamiento de créditos y los límites de gasto o de uso requieren el cambio correspondiente en la cuenta o en el límite; los reintentos por sí solos no restablecerán el acceso.
¿Qué debo comprobar si recibo un error 401 de OpenAI durante la extracción?
Confirma que la clave de API sea correcta y esté activa, que la solicitud use la organización prevista y que la cuenta pertenezca a esa organización. Si hay una lista de IP permitidas, comprueba que la solicitud provenga de una IP autorizada.
¿Una respuesta correcta de la API garantiza que el JSON cumpla el esquema?
No. Analiza el texto devuelto y valida el objeto resultante con el JSON Schema de tu aplicación antes de utilizarlo. Comprueba también que el endpoint, el modelo y el SDK seleccionados admitan los parámetros de salida estructurada de la solicitud.
¿Qué información debo conservar si el error persiste?
Registra el modelo, el código y el mensaje de error, la fecha y hora con su zona horaria, y los detalles y encabezados pertinentes de la solicitud. Oculta las credenciales y los datos de entrada sensibles antes de registrar o compartir la información de diagnóstico.
Artículos relacionados
Guides
Estimación del costo de la API de Grok Imagine Image para un flujo de extracción JSON
Estima los cargos de generación de imágenes de Grok Imagine Image, identifica los costos de extracción no disponibles y valida registros estructurados frente a un esquema JSON.
Guides
Guía de costes de la API de Qwen4 Max para extracción con JSON Schema
Estima los costes de extracción con Qwen4 Max por documento y por cada 100.000 documentos, incluidos los reintentos, los supuestos de caché y la validación con JSON Schema.
Guides
Costes de la API de GPT Image 2 para extracción estructurada: una estimación basada en supuestos
Estima los costes de una carga de trabajo con GPT Image 2 a partir de supuestos explícitos sobre tokens y descubre por qué debes verificar la compatibilidad con extracción en JSON antes de presupuestar un flujo de producción.
Guides
Costes de la API de GPT 6.2 Sol para extracción estructurada: una estimación reproducible
Estima los costes de extracción estructurada con GPT 6.2 Sol a partir de supuestos explícitos sobre tokens, reintentos, caché y tramos de contexto.