GuidesOneMux

Fallos de la API de OpenAI en producción: diagnosticar, reintentar y recuperarse de forma segura

Flujo de trabajo práctico para diagnosticar errores de autenticación, límites de solicitudes, tiempos de espera, fallos del servidor y respuestas malformadas de OpenAI, y decidir qué reintentar, corregir o enviar a recuperación.

AI

Resumen · TL;DR

La gestión de errores en producción empieza por clasificar el fallo, no por reintentar cada solicitud. Esta guía distingue los errores de configuración y cuota de los límites temporales, los tiempos de espera, los fallos del servidor y las respuestas no válidas; luego presenta un patrón de reintentos limitados en JavaScript y una lista de verificación para la recuperación.

Puntos clave

  • No reintentes errores de autenticación, permisos, solicitudes malformadas o créditos agotados sin corregir antes la causa.
  • Ante límites de solicitudes y sobrecarga, respeta `Retry-After` cuando esté presente y limita los reintentos con retroceso exponencial y variación aleatoria.
  • Un tiempo de espera no demuestra que la operación haya fallado; evita repetir a ciegas tareas que no sean idempotentes.
  • Valida las respuestas satisfactorias antes de confirmar el estado de los flujos posteriores y conserva suficiente contexto para recuperarte de forma segura.
En esta página (6)

Regla para producción: clasifica antes de reintentar

Cuando falla una llamada a la API de OpenAI, la pregunta útil no es simplemente «¿Debería reintentar?», sino «¿Qué indicios muestran que el fallo es temporal y qué ocurriría si se duplicara la solicitud?». Un flujo de trabajo de producción debe clasificar el error, aplicar una acción limitada y conservar el estado del trabajo si no puede continuar de forma segura.

OpenAI documenta causas distintas para los errores de autenticación, los límites de solicitudes, los créditos agotados o los límites de gasto, los errores del servidor y los modelos sobrecargados. El código de estado por sí solo no siempre basta: revisa también el código y el mensaje del error. Consulta la guía de códigos de error de OpenAI para conocer las causas y soluciones documentadas.

Diagnóstico según el tipo de fallo

SíntomaAcción probable¿Reintentar?
Error de autenticación 401Comprueba que la clave de API sea correcta y esté activa, y que se esté usando la organización prevista. Si está configurada, revisa también la lista de IP permitidas.No, hasta corregir las credenciales o el acceso.
Solicitud incorrecta 400Revisa el mensaje y los parámetros de la solicitud, incluidos los datos de entrada requeridos, la codificación, el formato y el tamaño.No, hasta corregir la solicitud.
Límite de solicitudes 429 o mensaje «slow down»Reduce la concurrencia o la frecuencia de solicitudes. Respeta Retry-After cuando esté presente y luego aumenta el tráfico gradualmente.Sí, dentro de una política de reintentos limitada.
Límite 429 de créditos, gasto o usoRevisa error.code y restablece los créditos o resuelve el límite correspondiente.No. Repetir la misma solicitud no restablecerá el acceso.
Error del servidor 500 o sobrecarga 503Espera brevemente, respeta Retry-After cuando esté presente y reintenta sin superar el límite.Por lo general, con medidas de seguridad.
Tiempo de espera del cliente o error de conexiónComprueba la red, el proxy, TLS y el firewall; determina si la solicitud pudo haberse completado.A veces; primero considera los efectos de duplicarla.
Estado satisfactorio, pero respuesta inutilizableValida la estructura de la respuesta y los campos obligatorios antes de avanzar en el flujo de trabajo.No automáticamente. Trátalo como un fallo independiente de calidad de datos o de protocolo.

La guía de OpenAI señala que RateLimitError de Python corresponde a 429 e InternalServerError a 503; por lo tanto, una sobrecarga puede llegar con un estado distinto del que esperaba un controlador anterior. En cualquier cliente, usa tanto el estado como los detalles del error, en lugar de asumir que toda sobrecarga es un 429.

Patrón de reintentos limitados en JavaScript

Requisitos previos: una versión actual del SDK de JavaScript de OpenAI, una clave de API configurada y un flujo de trabajo capaz de decidir de forma segura si es aceptable repetir una solicitud. Este ejemplo ilustrativo reintenta solo algunos fallos temporales. No demuestra que una solicitud que agotó el tiempo de espera no se haya procesado.

import OpenAI from "openai";

const client = new OpenAI();

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function retryAfterMs(error) {
  const value = error.headers?.get?.("retry-after");
  if (!value) return null;

  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);

  const dateMs = Date.parse(value);
  return Number.isNaN(dateMs) ? null : Math.max(0, dateMs - Date.now());
}

function isRetryable(error) {
  const code = error.code;
  if ([
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
  ].includes(code)) return false;

  return error instanceof OpenAI.RateLimitError ||
    (error instanceof OpenAI.APIError &&
      [500, 503].includes(error.status));
}

async function createResponseWithRetry(input, maxRetries = 3) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await client.responses.create({
        model: "YOUR_MODEL",
        input,
      });
    } catch (error) {
      if (!isRetryable(error) || attempt >= maxRetries) throw error;

      const exponentialMs = Math.min(10_000, 500 * 2 ** attempt);
      const jitterMs = Math.floor(Math.random() * 250);
      const delayMs = retryAfterMs(error) ?? exponentialMs + jitterMs;
      await sleep(delayMs);
    }
  }
}

YOUR_MODEL es un marcador de posición, no una recomendación de modelo. El ejemplo ilustra el control de reintentos, no un comportamiento probado en todas las versiones del SDK o todos los endpoints. Confirma que el SDK exponga los encabezados de respuesta como se muestra en la versión instalada; de lo contrario, usa el mecanismo admitido para leerlos. Establece un plazo límite para todo el flujo de trabajo, además de un número máximo de reintentos, para que un trabajo bloqueado no espere indefinidamente.

No añadas errores de autenticación, solicitudes incorrectas, permisos o cuotas a isRetryable. Corrige primero la configuración o el acceso. Considera también establecer un presupuesto de reintentos por trabajo y un límite de concurrencia a nivel de cola: los reintentos pueden agravar un pico de tráfico si todos los trabajadores repiten la solicitud de inmediato.

Los tiempos de espera y las respuestas malformadas requieren reglas de recuperación

Un tiempo de espera significa que el cliente no recibió una respuesta a tiempo; no permite determinar si el servidor completó la operación. Antes de reintentar, decide si es aceptable duplicar el trabajo. En tareas con acciones posteriores importantes, guarda un identificador y el estado del trabajo, y procura que las escrituras posteriores sean idempotentes cuando sea posible. Si el resultado es incierto, marca el trabajo para conciliación en vez de iniciar repetidamente la tarea a ciegas.

Trata la validación de la respuesta como un paso independiente del flujo de trabajo. Comprueba que el objeto de respuesta exista, que incluya el contenido esperado y que cualquier salida estructurada se pueda analizar y cumpla el esquema de tu aplicación. Una respuesta que no supere la validación no debe registrarse como resultado satisfactorio. Guarda información de diagnóstico segura y luego envíala a un proceso limitado de corrección o revisión; no des por hecho que repetir la misma solicitud resolverá el contenido malformado.

Lista de verificación operativa

  1. Registra la fecha y hora con zona horaria, el endpoint, el modelo, el estado HTTP, el tipo y el código del error, y un identificador de correlación seguro de la solicitud.
  2. Nunca registres claves de API ni datos de entrada confidenciales. Conserva solo los detalles de la solicitud que sean necesarios para reproducir el fallo de forma segura.
  3. Reintenta únicamente los fallos temporales, con un número máximo de intentos, espera, variación aleatoria y plazo límite general.
  4. Respeta Retry-After cuando se proporcione; reduce aún más el ritmo si el límite de solicitudes persiste.
  5. Distingue el agotamiento de los reintentos del fallo permanente para que los operadores puedan inspeccionar y volver a ejecutar los trabajos aptos.
  6. Si los errores persisten, recopila el modelo, el mensaje y el código del error, los datos y encabezados de la solicitud sin secretos, la fecha y hora con zona horaria y cualquier otro contexto pertinente. OpenAI recomienda proporcionar estos detalles al soporte.

Conclusión

Los flujos de trabajo fiables con la API de OpenAI distinguen la presión temporal sobre el servicio de los errores que requieren cambiar la configuración o los límites. Reintenta con cuidado ante la limitación de solicitudes y los fallos del servicio; corrige los errores de autenticación y de solicitud; y trata los tiempos de espera y las salidas no válidas como estados explícitos de recuperación. Esta clasificación evita que un ciclo de reintentos convierta una llamada fallida en un incidente de producción mayor.

FAQ

¿Debería reintentar todas las respuestas 429 de la API de OpenAI?

No. Reintenta las respuestas por límite de solicitudes con pausas, un número limitado de intentos y `Retry-After` cuando esté presente. Un 429 causado por créditos agotados o por un límite de gasto o uso requiere resolver ese límite; repetir la llamada no restablecerá el acceso. Revisa el código del error.

¿Cómo debería gestionar un flujo de trabajo un tiempo de espera de la API de OpenAI?

Trata el resultado como incierto: el cliente pudo agotar el tiempo de espera aunque el procesamiento se haya completado. Antes de reintentar, considera los efectos de duplicar la operación, usa operaciones posteriores idempotentes cuando sea posible y envía los trabajos ambiguos a conciliación.

¿Qué debería hacer si la API devuelve una respuesta malformada?

Valida la estructura de la respuesta y los campos obligatorios antes de guardarla o actuar en función de ella. No marques el trabajo como satisfactorio, registra información de diagnóstico segura y utiliza un proceso controlado de corrección o revisión en lugar de repetir automáticamente la misma solicitud.

¿Un 503 significa lo mismo que un 429?

No. La guía de OpenAI citada describe las respuestas 429 por límite de solicitudes y las respuestas 503 por sobrecarga del modelo como casos distintos. Un cliente debería revisar el estado y los detalles del error, y gestionar ambos cuando corresponda, en vez de asumir que la sobrecarga siempre aparece como 429.

Artículos relacionados