Los errores de OpenAI API parecen muy variados, pero antes de nada solo hay que distinguir cinco capas: si la petición salió, si la identidad es correcta, si la dirección y el modelo son correctos, si los parámetros son válidos y si se agotó la cuota o el límite de velocidad. Siguiendo un orden de diagnóstico, la mayoría de los problemas se localizan en minutos.

Este artículo desglosa por código de estado los 401, 403, 404, 400, 429 y 5xx, y ofrece comandos mínimos de reproducción, estrategias de reintento y un orden fijo de diagnóstico. Los nombres de modelo y la configuración de la pasarela se rigen por los precios de modelos y la documentación de integración del sitio.

Nota: OpenAI, GPT y ChatGPT son marcas de sus respectivos titulares. Este artículo toma como ejemplo el comportamiento habitual de las interfaces en octubre de 2026; los códigos de error y las reglas de límite se rigen por la documentación oficial y las respuestas reales.

1. Conserva primero tres pruebas

Antes de diagnosticar, guarda estas tres cosas:

  1. El código de estado HTTP.
  2. error.type, error.code y error.message del cuerpo de la respuesta.
  3. x-request-id de las cabeceras.

El ID de petición es el dato más útil al hablar con el proveedor. Sin él solo puedes describir "falló una vez sobre tal hora"; con él se localiza la petición concreta, el proveedor upstream concreto y la facturación concreta.

Código Tipo habitual Primera interpretación
400 invalid_request_error Problema de parámetros, JSON o longitud de contexto
401 authentication_error Clave ausente, incorrecta o caducada
403 permission_error La clave no tiene acceso a ese modelo o proyecto
404 not_found_error Base URL o nombre de modelo incorrectos
429 rate_limit_error / insufficient_quota Límite de velocidad o saldo insuficiente
500/502/503/504 server_error Fallo upstream o corte de red

2. 401 y 403: identidad y permisos

El núcleo del 401 es "el servidor no reconoce esta clave". Causas habituales:

  • La cabecera no lleva Authorization: Bearer.
  • Al copiar la clave se añadieron espacios o saltos de línea, o quedó truncada.
  • La clave se eliminó, se rotó o el proyecto al que pertenece está desactivado.
  • Se envió una clave de pasarela a la dirección oficial, o una clave oficial a la dirección de la pasarela.
  • La variable de entorno está mal escrita y en realidad se envía una cadena vacía.

El 403 suele significar "te reconozco, pero no te dejo hacer esto". Por ejemplo, la clave no tiene permiso para ese modelo, la organización está restringida o el proyecto no tiene habilitada la capacidad correspondiente. Ante un 403 no reintentes una y otra vez: revisa primero el proyecto de la clave y los permisos de modelo en la consola.

Una autocomprobación rápida:

curl -sS "https://api.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Si lista los modelos, la clave y la dirección son básicamente correctas; si sigue dando 401, revisa primero la clave y la variable de entorno.

3. 404: la dirección o el modelo no existen

Un 404 no siempre significa "la interfaz cerró"; lo más habitual es una ruta mal escrita. Casos frecuentes:

Síntoma Causa Solución
404 page not found A la Base URL le sobra o le falta /v1 Escribe según la documentación: https://api.zhongshangqihang.com/v1
model_not_found Nombre de modelo mal escrito o no habilitado Copia el nombre desde la página de precios de modelos
404 con doble barra en la ruta Se añadió un / de más al concatenar la URL Elimina las barras duplicadas
El SDK devuelve 404 base_url y ruta de interfaz duplicadas Deja un solo /v1

Para diagnosticar, envía primero una petición mínima con curl y descarta problemas de concatenación de URL del SDK. Si curl funciona y el SDK no, el problema suele estar en base_url, el proxy o la versión del SDK.

4. 400: parámetros y contexto

Un 400 indica que la petición no es válida y que reintentar no sirve. Causas frecuentes:

  • JSON mal formado, como comas finales, comillas simples o saltos de línea sin escapar.
  • Parámetros que el modelo no admite, como ciertos parámetros de muestreo.
  • max_tokens por encima del límite del modelo.
  • Entrada que supera la ventana de contexto y devuelve context_length_exceeded.
  • Formato o tamaño de imagen incorrectos, o URL inaccesible.
  • Esquema de herramienta inválido o campos obligatorios ausentes.

El orden de tratamiento es: reduce primero a la petición mínima y vuelve a añadir los parámetros uno a uno. No cambies cinco cosas a la vez, porque si el error desaparece no sabrás cuál lo causó.

5. 429: ¿límite de velocidad o saldo insuficiente?

El 429 es el código que más se malinterpreta. Tiene al menos dos significados:

Código de error Significado Tratamiento
rate_limit_exceeded Frecuencia, velocidad de tokens o concurrencia por encima del límite Reducir concurrencia, hacer cola, retroceso exponencial
insufficient_quota Saldo insuficiente o cuota agotada Recargar, cambiar de clave, revisar la cuota del proyecto

Mira primero el cuerpo y las cabeceras. retry-after indica cuánto conviene esperar; x-ratelimit-remaining-requests y x-ratelimit-remaining-tokens muestran cuánta cuota queda. Si el remanente es 0, esperar más no sirve: hay que aguardar el reinicio de la ventana o ampliar el límite.

Una lógica de reintento utilizable:

import random
import time
from openai import OpenAI

client = OpenAI(
    api_key="sk-tu-clave",
    base_url="https://api.zhongshangqihang.com/v1",
)

def chat(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="gpt-5.5",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=500,
                timeout=60,
            )
            return resp.choices[0].message.content
        except Exception as exc:
            status = getattr(exc, "status_code", None)
            if status not in (429, 500, 502, 503, 504) or attempt == retries - 1:
                raise
            wait = min(2 ** attempt, 16) + random.random()
            print(f"{status}, reintento en {wait:.1f} s: {exc}")
            time.sleep(wait)
    raise RuntimeError("unreachable")

Reintentar solo sirve para 429, 5xx y errores de red. Reintentar un 400, 401, 403 o 404 solo desperdicia tiempo y cuota.

6. 5xx: fallos upstream y problemas de red

500, 502, 503 y 504 normalmente no indican que tu petición esté mal, sino que el servicio upstream falla, la pasarela agota el tiempo o la red se interrumpe. Principios de tratamiento:

  1. Reintenta una o dos veces con retroceso exponencial y jitter aleatorio.
  2. En peticiones en streaming, comprueba si ya se recibió parte del contenido; la salida parcial puede haberse facturado.
  3. Las operaciones idempotentes pueden reintentarse automáticamente; las no idempotentes necesitan una clave de deduplicación.
  4. Ante 5xx masivos, consulta la página de estado del proveedor; no aumentes la concurrencia a ciegas.
  5. Registra el ID de petición para que el proveedor pueda localizarla.

Si solo tus peticiones dan 5xx y las de otros equipos funcionan, revisa primero el tamaño del cuerpo, la configuración de timeout y la cadena de proxy.

7. Un orden de diagnóstico fijo

Ante un error, sigue este orden sin saltarte pasos:

  1. Envía una petición mínima con curl y confirma dirección y clave.
  2. Compara la dirección oficial y la de la pasarela y confirma que no mezclas claves.
  3. Comprueba que la Base URL solo tenga un /v1.
  4. Comprueba que el nombre del modelo se copió de la página de precios y está habilitado.
  5. Elimina los parámetros opcionales y confirma que la petición mínima funciona.
  6. Revisa el saldo, la cuota del proyecto y el límite de la clave.
  7. Revisa las cabeceras del 429 para distinguir límite de velocidad y saldo.
  8. Consulta la página de estado del proveedor para descartar un fallo upstream.
  9. Guarda el ID de petición, el código de estado y el cuerpo, y contacta con soporte.

8. Preguntas frecuentes

¿Un 429 siempre significa que llamo demasiado rápido?

No. Un 429 puede ser frecuencia o concurrencia por encima del límite, o saldo insuficiente. Mira error.code y las cabeceras; no bajes la velocidad sin más.

¿Basta con cambiar la clave ante un 401?

Cambiar la clave descarta problemas de la propia clave, pero si hay direcciones mezcladas, una variable de entorno vacía o un proyecto sin permisos, cambiar de clave no servirá. Confirma primero a dónde se envía realmente la petición.

¿Un 404 significa que el modelo se retiró?

En la mayoría de los casos es la Base URL o el nombre del modelo. Llama primero a /v1/models con curl y contrasta el nombre con la página de precios.

¿Se puede reintentar un 5xx sin límite?

No. Define un número máximo de reintentos y un timeout total para no acumular peticiones durante el fallo. En streaming, considera además que la salida parcial puede estar facturada.

¿Cómo distinguir un error de la pasarela de uno oficial?

Mira primero el formato del cuerpo y el ID de petición; después solicita la dirección oficial y la de la pasarela con la misma clave y el mismo modelo. La capa que reproduzca el fallo de forma estable es donde está el problema.

Siguiente paso

Prepara primero la petición mínima, el log de uso y la estrategia de reintentos, y después conecta el tráfico de negocio. Si necesitas recarga en yuanes y una entrada unificada para varios modelos, regístrate en la pasarela de IA de Zhongshang Qihang; los nombres de modelo y los precios se rigen por los precios de modelos.

Lecturas relacionadas: