Los errores de la API de GLM tienen dos capas: el código de estado HTTP en el exterior y el código de negocio dentro del cuerpo de la respuesta. Mirar solo la capa externa lleva a diagnósticos equivocados; por ejemplo, una cuenta con saldo pendiente también devuelve 429. El orden de diagnóstico debería ser: leer primero el código de negocio y el mensaje, localizar después el ID de solicitud o el ID de error, reproducir con una solicitud mínima y solo al final cambiar parámetros o de modelo.

Este artículo separa los casos 401, 403, 404, 429, 5xx y timeout, y ofrece una tabla de códigos de negocio, código de manejo de errores y una lista de comprobación antes de contactar al soporte. Los modelos y precios se rigen por precios de modelos del sitio.

Nota: Zhipu, GLM y BigModel son marcas de sus respectivos titulares. Este artículo solo ofrece una explicación técnica y no implica subordinación ni relación de agencia con Zhipu. Los códigos de error, los criterios de limitación y el comportamiento de la interfaz pueden cambiar según la versión; prevalecen la documentación oficial y la respuesta real.

1. Distingue primero las dos capas del error

El código de estado HTTP describe el resultado en la capa de protocolo; el código de negocio describe la causa concreta. Un mismo 401 puede deberse a que falta el encabezado de autenticación, a un token vencido o a una verificación secundaria; un mismo 429 puede ser un límite de velocidad, un modelo ocupado, saldo pendiente o el límite del plan. Registrar el código de negocio en los logs es el paso que más mejora la eficiencia del diagnóstico.

HTTP Códigos de negocio habituales Significado ¿Conviene reintentar?
401 1000 / 1001 / 1003 / 1005 Fallo de autenticación, falta el encabezado, token vencido, verificación secundaria No; corrige primero las credenciales
403 1220 Sin permiso para esa API o modelo No; revisa plan y permisos
400 1210 / 1211 / 1221 / 1222 / 1261 Parámetros incorrectos, modelo inexistente, API retirada o inexistente, prompt demasiado largo No; modifica la solicitud
429 1113 Cuenta con saldo pendiente No; recarga primero
429 1302 / 1305 Límite de velocidad, volumen de acceso al modelo demasiado alto Sí; retroceso y reintento
429 1308 / 1310 Límite del periodo, se restablece según next_flush_time Espera el restablecimiento, no insistas
429 1311 / 1313 / 1315 El plan no incluye el modelo, límite de uso justo, tipo de clave incompatible No; revisa plan y clave
500 1200 / 1230 / 1234 Error interno, fallo de proceso, error de red (incluye ID de error) Sí; retroceso y conserva el ID

La tabla recoge los mapeos más frecuentes; la lista completa está en la documentación oficial. Una interrupción de streaming puede no traer código de negocio, y la causa aparece en finish_reason o en el último fragmento de datos.

2. 401: cuatro tipos de fallo de autenticación

Un 401 significa que la identidad no superó la verificación y normalmente no tiene relación con la capacidad del modelo ni con el saldo. Los códigos oficiales distinguen las causas habituales:

  • 1000, fallo de autenticación: clave incorrecta, copiada de forma incompleta o ya eliminada.
  • 1001, falta el parámetro de autenticación en el encabezado: no hay Authorization: Bearer <key> o el proxy lo descartó.
  • 1003, token vencido: la clave tiene vigencia o ya se rotó en la consola.
  • 1005, verificación secundaria activada: completa la verificación que exige la plataforma.

Revisa en este orden:

  1. Confirma el formato del encabezado: un espacio después de los dos puntos y sin comillas ni saltos de línea alrededor de la clave.
  2. Imprime el prefijo de la variable de entorno para confirmar que no está vacía ni contiene un valor antiguo.
  3. Confirma el tipo de clave: las claves de API de modelo estándar, Coding Plan y equipo o empresa se administran por separado y no deben mezclarse.
  4. Confirma que la base URL y la clave pertenecen al mismo servicio: una clave oficial con la dirección oficial y una clave de pasarela con la dirección de la pasarela.
  5. Prueba con una clave nueva y una solicitud mínima para distinguir un problema de clave de uno de configuración del proxy o de la pasarela.

Copiar la clave desde una ventana de chat es la forma más habitual de introducir espacios o saltos de línea. Haz primero una solicitud que solo devuelva una palabra; con eso se descartan la mayoría de los errores básicos.

3. 403 y 404: permisos, rutas y nombres de modelo

El código de negocio más común del 403 es 1220, que indica que la cuenta actual no tiene permiso para esa API o modelo. Revisa si el plan incluye el modelo, si la clave pertenece al tipo de producto correspondiente y si se está llamando a una interfaz no habilitada. Reintentar no sirve en estos casos: hay que cambiar permisos o usar otra clave.

La mayoría de los 404 no significan que "el servicio esté caído", sino que la dirección es incorrecta: sobra o falta /v1 en la base URL, el SDK agrega la ruta y además se escribe a mano la ruta completa, o una regla de reescritura del proxy inverso altera la ruta. Un nombre de modelo incorrecto de GLM suele devolver 400 con 1211; una API retirada o inexistente corresponde a 1221 y 1222. Por eso, ante un 404 revisa primero la dirección; ante un 1211, el nombre del modelo.

El nombre del modelo debe tomarse de la documentación oficial y de la página de precios del sitio, no de memoria. Al actualizar un modelo, confirma primero en el entorno de pruebas que los parámetros siguen siendo compatibles.

4. 429: lee el código de negocio antes de decidir si reintentas

El 429 es el error que más se maneja mal. Al menos incluye cinco situaciones:

  • 1113, saldo pendiente: reintentar antes de recargar no tiene sentido.
  • 1302, límite de velocidad alcanzado: reduce la concurrencia o aplica retroceso.
  • 1305, volumen de acceso al modelo demasiado alto: suele estar ligado a la hora pico; aplica retroceso y, si hace falta, cambia a un modelo de respaldo.
  • 1308 y 1310, límite de uso del periodo alcanzado: el mensaje incluye la hora de restablecimiento; espera a que se recupere la cuota.
  • 1309, 1311, 1313 y 1315: plan vencido, modelo no habilitado, límite de uso justo o tipo de clave incompatible; solo cambia algo si ajustas la configuración.

Solo los límites transitorios como 1302 y 1305 admiten reintento automático; en los demás casos el reintento solo alarga la falla. El criterio de limitación (concurrencia, solicitudes por minuto o velocidad de tokens) varía según el plan y el modelo; consulta la consola y la documentación oficial.

5. 5xx y timeouts: localiza por separado

La serie 500 incluye 1200, error interno; 1230, fallo de proceso; y 1234, error de red. El 1234 suele traer un ID de error que debes conservar al contactar al soporte. Ante 5xx sostenidos, aplica retroceso y consulta después el estado del servicio o los avisos del proveedor; no reintentes a alta frecuencia.

El timeout debe analizarse en tres tramos: el timeout de conexión apunta a DNS, salida o proxy inaccesible; la lentitud del primer token suele deberse a cola en el upstream o a una entrada demasiado larga; el timeout de lectura suele venir de una salida muy larga o de un razonamiento prolongado. Los tres se tratan de forma distinta y no basta con aumentar el tiempo de espera.

Cuando una solicitud en streaming se interrumpe, puede no haber código HTTP de error ni código de negocio. Registra el contenido ya recibido y el último fragmento, revisa finish_reason y determina después si fue una fluctuación de red, un corte del proxy o un timeout del upstream. No guardes el contenido parcial como resultado completo.

6. ID de solicitud y logs: la evidencia del diagnóstico

No todos los endpoints oficiales devuelven un ID de solicitud con el mismo nombre; el nombre del campo depende de la respuesta real y de la documentación. En ingeniería, lo más seguro es registrar dos vías: un trace_id generado por el cliente que acompañe todos los reintentos y, al mismo tiempo, el cuerpo de error del upstream tal como llegó, con cualquier campo request id o error id.

Los logs deben incluir al menos: hora, trace_id, base URL, nombre del modelo, código de estado HTTP, código de negocio, mensaje de error, duración, número de reintentos y si fue streaming. De la clave registra solo los primeros caracteres o un hash; no guardes en disco el texto original del usuario ni la respuesta completa.

Estos campos no son solo para uso interno. Al contactar al soporte, un registro con trace_id, código de negocio y una solicitud mínima reproducible es mucho más útil que decir "a veces da error".

7. Reintentos y retroceso: ejemplo de código

El siguiente bloque desactiva los reintentos automáticos del SDK, decide si reintentar según el código de negocio e imprime juntos trace_id, estado y código. Los timeouts de red se tratan por separado y los reintentos tienen un límite.

import os
import random
import time
import uuid

import httpx
from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError

client = OpenAI(
    api_key=os.environ["GLM_API_KEY"],
    base_url=os.environ.get(
        "GLM_BASE_URL", "https://open.bigmodel.cn/api/paas/v4"
    ),
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
    max_retries=0,  # Desactiva los reintentos del SDK; los controla la lógica siguiente
)

RETRYABLE_CODES = {1302, 1305}  # Límite de velocidad y modelo ocupado; no incluye saldo ni plan

def ask(prompt: str, max_attempts: int = 4) -> str:
    trace_id = uuid.uuid4().hex[:12]
    for attempt in range(1, max_attempts + 1):
        try:
            resp = client.chat.completions.create(
                model=os.environ["GLM_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except APIStatusError as exc:
            code = None
            try:
                code = int(exc.response.json().get("code"))
            except Exception:
                pass
            print(
                f"trace={trace_id} attempt={attempt} "
                f"http={exc.status_code} code={code} "
                f"body={exc.response.text[:500]}"
            )
            retryable = exc.status_code >= 500 or (
                exc.status_code == 429 and code in RETRYABLE_CODES
            )
            if not retryable or attempt == max_attempts:
                raise
        except (APITimeoutError, APIConnectionError) as exc:
            print(f"trace={trace_id} attempt={attempt} err={type(exc).__name__}")
            if attempt == max_attempts:
                raise
        wait = min(2 ** (attempt - 1), 20) + random.uniform(0, 1)
        time.sleep(wait)
    raise RuntimeError("Se agotaron los reintentos")

Añade tres reglas: respeta primero el Retry-After que devuelva el servidor, si existe; controla el presupuesto de reintentos de forma global para evitar la suma de varios servicios; en solicitudes con efectos secundarios, usa una clave de idempotencia para confirmar el estado antes de reenviar.

8. Gestión de concurrencia: más eficaz que aumentar los reintentos

Los problemas de límite de velocidad no suelen resolverse con reintentos, sino con gestión en la entrada:

  • Asigna una clave independiente y un límite de concurrencia a cada servicio.
  • Divide las tareas por lotes y distribúyelas en horarios distintos para evitar picos puntuales.
  • Usa colas para amortiguar los picos; las tareas fallidas van a una cola con retraso en lugar de girar en el mismo lugar.
  • Monitorea la proporción de 429 y la latencia P95; si suben de golpe, reduce primero la concurrencia.
  • Prepara un modelo o una entrada de respaldo, pero confirma la compatibilidad de parámetros antes de cambiar.

Los valores concretos de concurrencia máxima, solicitudes por minuto y velocidad de tokens varían según el plan y el modelo; consulta la consola y la documentación oficial. No copies cifras ajenas: configura según tus propias mediciones.

9. Lista de comprobación antes de contactar al soporte

  1. Hora y zona horaria del incidente, y si las fallas se concentran.
  2. Base URL, ruta de la interfaz, nombre del modelo y método de solicitud.
  3. Código de estado HTTP, código de negocio y mensaje de error completo.
  4. ID de error o ID de solicitud; si no existe, el trace_id generado por ti.
  5. Una solicitud curl mínima reproducible, con la clave enmascarada.
  6. Si era streaming, si usaba contexto largo y si la configuración se cambió justo antes.
  7. Alcance: una clave, un proyecto o todos los servicios.

Con estos datos el equipo de soporte puede localizar el problema directamente en lugar de pedir información de ida y vuelta. Después de cada incidente, añade monitoreo y alertas; no esperes a que los usuarios reporten la falla.

10. Preguntas frecuentes

1. ¿Un 429 siempre significa límite de velocidad?

No. Un 429 también puede ser saldo pendiente (1113), límite del periodo (1308, 1310), falta de permiso del plan para el modelo (1311) o límite de uso justo (1313). Lee primero el código de negocio y decide después si aplicar retroceso, recargar o cambiar la configuración.

2. Cambié la clave y el 401 sigue fallando, ¿qué hago?

Revisa si el encabezado es Authorization: Bearer <key>, si la variable de entorno se carga, si el tipo de clave coincide con la interfaz, si la base URL y la clave pertenecen al mismo servicio y si el proxy inverso descarta el encabezado de autenticación.

3. ¿Conviene reintentar un timeout?

Solo aplica un número limitado de reintentos a fallos de conexión y timeouts de lectura, con retroceso exponencial. En operaciones con efectos secundarios, confirma primero si ya se ejecutaron para evitar pedidos o escrituras duplicadas.

4. ¿Cómo diagnosticar un corte a mitad de la salida en streaming?

Registra el contenido recibido, el último fragmento y finish_reason, y distingue entre fluctuación de red, corte del proxy y timeout del upstream. El cliente debe admitir reconexión y deduplicación, y no debe guardar contenido parcial.

5. ¿Qué hago si el error solo trae código de estado y ningún código de negocio?

Conserva el cuerpo y los encabezados completos de la respuesta, registra trace_id, base URL, nombre del modelo y una solicitud mínima reproducible, y contacta al proveedor. Si usas una pasarela, entrega también esos datos a la pasarela para facilitar el cotejo con los logs del upstream.

Siguiente paso

Crea primero una clave de prueba en ZSQH AI Gateway y simula una vez cada caso: 401, 403, 429, 5xx y timeout; después conecta el monitoreo de producción. Los modelos disponibles y la facturación están en precios de modelos.

Lecturas relacionadas