Cómo diagnosticar de forma segura errores de autenticación, límites de solicitudes, tiempos de espera y respuestas mal formadas de la API de OpenAI
Guía práctica y respetuosa con la privacidad para diagnosticar errores de autenticación, limitación de solicitudes, tiempos de espera y respuestas mal formadas de la API de OpenAI sin exponer credenciales ni datos de usuarios.
Resumen · TL;DR
La forma más segura de solucionar fallos de la API de OpenAI es clasificarlos antes de volver a intentarlo. Los errores de autenticación suelen requerir corregir una clave, organización, proyecto o configuración de IP; los errores de límite y cuota requieren ajustar el ritmo de solicitudes o hacer cambios administrativos; los tiempos de espera pueden ser transitorios; y las respuestas mal formadas deben investigarse como fallos de transporte, proxy o análisis. Registra metadatos de diagnóstico, no credenciales ni contenido original de usuarios.
Puntos clave
- No vuelvas a intentar errores de autenticación 401 ni fallos de facturación o cuota como si fueran errores de red temporales.
- Ante respuestas 429 por limitación de solicitudes y respuestas 503 por sobrecarga, respeta `Retry-After` cuando esté presente y aplica un retroceso exponencial acotado.
- Mantén las claves de API fuera del código fuente, los registros, los mensajes de excepción y las aplicaciones del lado del cliente.
- Trata una respuesta que no sea JSON o un fallo al analizar JSON como un problema independiente de transporte o proxy, y conserva únicamente un diagnóstico acotado y redactado.
- Al escalar un problema persistente, proporciona el modelo, el código de error, la marca de tiempo, la zona horaria y detalles sanitizados de la solicitud.
En esta página (7)
Es más fácil corregir los fallos de la API de OpenAI cuando se distinguen los errores de configuración, los problemas de capacidad, los fallos de red y los fallos al analizar respuestas. La primera pregunta de diagnóstico debería ser: ¿es probable que volver a intentarlo cambie el resultado?
Normalmente, reintentar una solicitud no resolverá un error 401. Un 429 causado por la velocidad de las solicitudes puede mejorar al reducir el ritmo, mientras que un 429 por créditos agotados o por un límite de gasto requiere un cambio en la cuenta o el proyecto. Un tiempo de espera puede ser transitorio, pero si se repite, podría indicar un problema de red, proxy o tamaño de la solicitud.
Los procedimientos que siguen usan JavaScript y conceptos de la biblioteca oficial de OpenAI descritos en la guía de códigos de error de OpenAI. El código muestra un patrón ilustrativo, no una integración de producción probada.
Antes de depurar: protege las credenciales y los datos de usuario
Antes de reproducir un error, toma estas precauciones:
- Guarda la clave de API en un gestor de secretos del lado del servidor o en una variable de entorno. No la incluyas nunca en código del navegador, aplicaciones móviles, sistemas de control de versiones ni solicitudes de soporte.
- Registra la hora de la solicitud, la categoría del endpoint, el identificador del modelo, el estado HTTP y, cuando esté disponible, el código de error estructurado.
- No registres encabezados
Authorization, cuerpos completos de solicitudes, cuerpos sin procesar de respuestas ni prompts con datos personales. - Si necesitas un prompt para diagnosticar el problema, guarda una muestra redactada o un identificador interno de solicitud estable en lugar del texto original.
- Limita la longitud de los datos de diagnóstico. Un proxy podría devolver una página de error HTML extensa, y un error del servicio ascendente podría contener datos que no pretendías conservar.
Una regla operativa útil es que los registros respondan qué falló y dónde, sin registrar qué dijo el usuario ni cómo autenticarse.
Diagnostica primero los errores de autenticación 401
Entre los casos documentados de error 401 se incluyen la autenticación no válida, una clave de API incorrecta, la falta de pertenencia a una organización y una dirección IP no autorizada. Un 403 puede indicar que el país, la región o el territorio no están admitidos.
Comprueba estos puntos en orden:
- Confirma que el servidor está leyendo el secreto previsto y que no se ha truncado, caducado, revocado ni sustituido.
- Confirma que la solicitud se envía al endpoint y al proyecto previstos.
- Si tu configuración usa un identificador de organización o una lista de permitidos de IP, comprueba ambos con la configuración del proyecto.
- Comprueba si la solicitud procede de una IP de salida distinta en desarrollo, en un contenedor o en un entorno alojado.
- Elimina los valores de las credenciales de cualquier salida de depuración antes de compartir los registros.
No uses reintentos automáticos para un 401 o un 403. Repetir la misma solicitud con credenciales no válidas puede generar ruido y dificultar el análisis del incidente. Corrige la configuración y luego envía una nueva solicitud.
Distingue la limitación de solicitudes 429 de los problemas de cuota y facturación
No todos los 429 significan «vuelve a intentarlo pronto». La guía de OpenAI distingue varios casos:
| Categoría del fallo | Acción probable | ¿Reintentar automáticamente? |
|---|---|---|
| Se alcanzó el límite de solicitudes | Espaciar las solicitudes y respetar Retry-After cuando esté presente | Sí, con límites |
slow_down | Reducir el ritmo de solicitudes y aumentarlo gradualmente | Sí, con cautela |
| Saldo de créditos agotado | Añadir créditos | No |
| Límite de gasto de la organización o del proyecto | Cambiar el límite correspondiente | No |
| Límite de uso de la organización | Solicitar un límite aprobado más alto o contactar con soporte | No |
Un bucle de reintentos debe comprobar el estado HTTP y el código de error específico, en lugar de tratar todos los 429 de la misma manera. Establece un número máximo de intentos y usa retroceso exponencial con aleatoriedad para evitar que varios procesos reintenten simultáneamente. Si aparece Retry-After, prioriza ese intervalo, sin superar tu propio tiempo máximo de espera.
Ten en cuenta también las respuestas 503. La documentación de referencia identifica la sobrecarga del modelo con server_is_overloaded y recomienda respetar Retry-After cuando esté presente antes de reintentar. En la biblioteca de Python, la sobrecarga puede representarse mediante InternalServerError, mientras que las respuestas 429 usan RateLimitError; los controladores no deben dar por sentado que la sobrecarga siempre llega como un 429.
Investiga los tiempos de espera y los fallos de conexión
La biblioteca oficial de Python documenta APITimeoutError para las solicitudes que agotan el tiempo de espera y APIConnectionError para los problemas de conexión. Estos son algunos puntos habituales de diagnóstico:
- Tiempo de espera antes de recibir una respuesta: revisa la configuración del tiempo de espera del cliente, las rutas de red, los proxies, los firewalls y el tamaño de la solicitud.
- Fallo de conexión: comprueba DNS, los certificados TLS, las reglas del firewall para el tráfico saliente y la configuración del proxy.
- Fallos del servidor que se repiten: consulta la página de estado del servicio y conserva las marcas de tiempo sanitizadas para soporte.
Un tiempo de espera no demuestra que el servidor no haya procesado la solicitud. Si las operaciones duplicadas pueden causar problemas, diseña la aplicación para que los reintentos puedan conciliarse de forma segura; por ejemplo, asociando la operación a un registro de solicitud propio. No intentes solucionar los tiempos de espera aumentando indefinidamente su duración ni reintentando sin límite.
Gestiona las respuestas mal formadas sin filtrar contenido
«Respuesta mal formada» puede describir varios problemas: una solicitud no válida que produce un BadRequestError, una respuesta que no cumple el esquema esperado o un proxy que devuelve HTML o datos truncados en lugar de JSON. La guía de OpenAI describe BadRequestError como una solicitud mal formada o incompleta y recomienda comprobar los parámetros obligatorios, la codificación, el formato y el tamaño.
Si trabajas con clientes HTTP sin procesar o middleware, haz estas comprobaciones por separado:
- Comprueba el estado HTTP y
Content-Typeantes de analizar la respuesta. - Analiza el JSON dentro de un bloque protegido.
- Valida que existan los campos obligatorios antes de usarlos.
- Registra solo el estado, el tipo de contenido, la longitud de la respuesta y, si la política lo permite, un fragmento acotado y redactado.
- No incluyas la clave de API, el prompt completo ni la respuesta completa en un mensaje de error de análisis.
Un envoltorio ilustrativo podría tener este aspecto:
async function parseSafeResponse(response) {
const contentType = response.headers.get("content-type") || "";
const body = await response.text();
if (!contentType.toLowerCase().includes("application/json")) {
throw new Error(`Unexpected response type: ${contentType}; length=${body.length}`);
}
try {
return JSON.parse(body);
} catch {
throw new Error(`Invalid JSON response; length=${body.length}`);
}
}
Este ejemplo excluye deliberadamente el cuerpo del error generado. En producción, añade una validación de esquema adecuada para el endpoint y conserva los datos sin procesar solo mediante un proceso de diagnóstico controlado y revisado en materia de privacidad.
Patrón de controlador de errores respetuoso con la privacidad
El ejemplo oficial de JavaScript distingue entre errores de conexión, errores de límite de solicitudes y otros errores de API. Amplía esa idea clasificando los errores sin imprimir secretos ni datos de usuario:
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
try {
const response = await client.responses.create({
model: process.env.OPENAI_MODEL,
input: "Redacted diagnostic input"
});
console.log({ ok: true, hasOutput: Boolean(response.output_text) });
} catch (error) {
const details = {
name: error?.name,
status: error?.status,
code: error?.code
};
if (error instanceof OpenAI.AuthenticationError) {
console.error("Authentication failed", details);
} else if (error instanceof OpenAI.RateLimitError) {
console.error("Rate limit or quota response", details);
} else if (error instanceof OpenAI.APIConnectionError) {
console.error("Connection failed", details);
} else if (error instanceof OpenAI.APIError) {
console.error("OpenAI API error", details);
} else {
console.error("Unexpected local error", { name: details.name });
}
}
Verifica los nombres de las clases y el comportamiento de los endpoints con la versión del SDK que despliegues. No des por sentado que todos los endpoints compatibles con proveedores admiten todos los parámetros del SDK o campos de respuesta.
Cuándo escalar el problema
Para los fallos persistentes, la guía de OpenAI recomienda proporcionar el modelo, el mensaje y el código de error, los datos y encabezados de la solicitud, la marca de tiempo, la zona horaria y otros detalles pertinentes. Antes de compartir esa información, sanitízala: sustituye las credenciales, elimina las cookies, redacta los datos personales y, cuando sea posible, resume el cuerpo de la solicitud. No publiques información sensible en un foro público.
La decisión práctica es sencilla: corrige los problemas de autenticación y cuota; reduce el ritmo ante limitaciones y sobrecargas; revisa los límites de red cuando se agote el tiempo de espera; y aísla los fallos de análisis sin conservar datos privados.
FAQ
¿Hay que reintentar todas las respuestas 429 de OpenAI?
No. Reintenta con cautela las respuestas causadas por el ritmo de las solicitudes o por `slow_down`, aplicando retroceso y respetando `Retry-After` cuando esté presente. No esperes que los reintentos solucionen los créditos agotados, los límites de gasto ni los límites de uso de la organización.
¿Por qué un error de sobrecarga de OpenAI puede aparecer como 503 en lugar de 429?
La guía de errores de OpenAI documenta la sobrecarga del modelo como un 503 con el código `server_is_overloaded`. Los controladores de errores deben comprobar tanto el estado como el código, en lugar de dar por sentado que la sobrecarga siempre es una respuesta de límite de solicitudes.
¿Qué debería registrar ante un error de autenticación de OpenAI?
Registra la marca de tiempo, el entorno, la categoría del endpoint, el estado y el código de error sanitizado. No registres la clave de API, el encabezado `Authorization`, el cuerpo completo de la solicitud ni el prompt original del usuario.
¿Cómo puedo diagnosticar una respuesta JSON no válida?
Comprueba el estado HTTP y `Content-Type` antes de analizar la respuesta. Si la política lo permite, conserva solo un diagnóstico acotado y redactado, e inspecciona los proxies o el middleware que podrían devolver HTML, truncar datos o modificar la respuesta.
Artículos relacionados
Guides
Diagnóstico de fallos de la OpenAI API en un flujo de clasificación de soporte con aprobación humana
Una guía práctica para gestionar errores de autenticación, límites de tasa, tiempos de espera agotados y respuestas del modelo mal formadas, sin que los resultados fallidos de clasificación lleguen a los clientes.
Guides
Diagnosticar fallos de la API de OpenAI en la respuesta a preguntas sobre documentos
Guía práctica para solucionar problemas de autenticación, límites de frecuencia, tiempos de espera y respuestas con atribución de fuentes no válidas.
Guides
Extracción estructurada segura con OpenAI: claves, registros, permisos y rotación
Flujo de trabajo práctico para extraer datos estructurados con OpenAI: aislar credenciales, restringir permisos, validar la salida JSON, redactar registros y rotar claves de forma segura.
Guides
Protege las claves de API de OpenAI para clasificar solicitudes de soporte
Flujo práctico de seguridad para usar OpenAI en la clasificación de solicitudes de soporte: protege las claves de API, redacta los registros, limita los permisos, rota las credenciales y exige aprobación humana.