Los errores de la API de Grok se dividen en cuatro grandes grupos: credenciales y permisos, ruta y nombre del modelo, límites de frecuencia y cuota, y red y timeouts. El orden de resolución debería ser: primero el código de estado HTTP y el tipo de error, después el ID de la petición y solo al final el prompt o los parámetros del modelo. Si inviertes el orden, es fácil confundir un problema de configuración con un problema del modelo.

Este artículo desglosa las cuatro categorías —401, 404, 429 y timeouts— y ofrece causas, pasos de diagnóstico y código de reintentos reutilizable. Los modelos y los precios se rigen por los precios de modelos del sitio.

Nota: xAI y Grok son marcas de sus respectivos titulares; este artículo solo ofrece una explicación técnica. Los tipos de error y el comportamiento de las interfaces pueden cambiar con las versiones. Este artículo se basa en los casos habituales de octubre de 2026; en última instancia, rige la documentación oficial de xAI.

1. Mira primero el código de estado, no toques aún el prompt

Código Significado habitual ¿Reintentar?
400 Parámetros, formato o longitud de contexto incorrectos Corrige la petición y vuelve a intentarlo
401 Clave ausente, incorrecta, vencida o que no coincide con la dirección No reintentar; corrige primero la credencial
403 La cuenta o la clave no tienen permiso, o hay restricciones regionales o de términos No reintentar; revisa permisos y estado de la cuenta
404 Ruta incorrecta o nombre de modelo inexistente No reintentar; revisa dirección y nombre del modelo
429 Se superó el límite de frecuencia, concurrencia o tokens Reintentar con retroceso
500 Error interno del proveedor Reintentar con retroceso
502 o 503 Gateway o proveedor temporalmente no disponible Reintentar con retroceso
504 El gateway agotó el tiempo de espera del proveedor Reducir carga y reintentar

Conserva el ID de la petición que aparece en la respuesta. Para que un proveedor investigue, un ID de petición vale más que diez capturas de pantalla. En los registros, anota al menos la hora, el código de estado, el tipo de error, el nombre del modelo y el ID de la petición; no registres la clave completa ni contenido sensible.

2. 401: revisa primero las cabeceras y después la clave

Un 401 indica que la identidad no superó la validación; no tiene relación con el saldo ni con la capacidad del modelo. Revisa en este orden:

  1. Si la cabecera de autenticación está escrita como Authorization: Bearer <clave>. La entrada compatible con OpenAI de Grok no usa x-api-key.
  2. Si la clave tiene espacios, saltos de línea o comillas de más antes o después. Copiar desde una ventana de chat es la causa más común.
  3. Si la clave y la URL base provienen del mismo proveedor. Una clave oficial contra la dirección del gateway, o una clave del gateway contra la dirección oficial, fallará.
  4. Si la clave fue revocada, caducó o el proyecto al que pertenece no tiene permiso de llamada.
  5. Si la variable de entorno se cargó realmente. Imprime solo los primeros caracteres de la clave para confirmarlo; no escribas el valor completo en los registros.
  6. Si la URL base apunta al entorno correcto y la ruta es /v1/chat/completions.
export GROK_API_KEY="sk-tu-clave"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "messages": [{"role": "user", "content": "Responde solo OK"}],
    "max_tokens": 16
  }'

Si devuelve 200, la clave, la dirección y el nombre del modelo funcionan. Si sigue devolviendo 401, prueba la misma clave contra otra entrada: así podrás distinguir si el problema está en la clave, en la configuración del gateway o en la capa de red.

3. 404: revisa la ruta y el nombre del modelo por separado

Un 404 normalmente no es un problema de la clave, sino de "el recurso que solicitas no existe". Hay cuatro causas habituales:

  • La URL base ya incluye /v1 y el código vuelve a concatenarlo, formando /v1/v1/chat/completions.
  • El endpoint está escrito como /completions o /responses, pero la entrada actual solo ofrece Chat Completions.
  • El nombre del modelo está mal escrito, o la cuenta o el grupo no tienen habilitado ese modelo.
  • La URL base termina con una barra extra y la concatenación produce una doble barra o una ruta incorrecta.

Orden de diagnóstico: primero haz una petición curl a la ruta estándar que indica la documentación oficial; después copia el nombre del modelo desde la consola o desde los precios de modelos. No escribas el nombre de memoria ni reutilices directamente nombres de modelos de otras plataformas.

4. 429: un límite de frecuencia no es saldo insuficiente

Un 429 indica que la petición superó un límite de velocidad o de cuota. Escenarios habituales:

  • Se excedió el número de peticiones o de tokens por minuto.
  • La concurrencia aumentó de golpe y agotó la cuota en poco tiempo.
  • Varios servicios comparten una misma clave y compiten por la cuota.
  • Los reintentos no aplican retroceso: cuanto más fallan, más reintentan, y se forma una tormenta de reintentos.
  • Las salidas largas consumen muchos tokens de salida y dejan menos margen para la concurrencia.
Síntoma Causa posible Qué hacer
429 concentrados en horas pico Pico de tráfico Formar cola y suavizar el envío
429 con una clave usada por varios servicios Cuota compartida Dividir claves por proyecto
Empeora después de reintentar Reintentos sin retroceso Retroceso exponencial con jitter aleatorio
Las peticiones largas reciben 429 primero Alto consumo de tokens de salida Reducir max_tokens o la concurrencia

Revisa primero el retry-after de la respuesta, si existe, y decide cuánto esperar. Usa los tipos de error del SDK en lugar de comparar cadenas del mensaje:

import random
import time
from openai import OpenAI, APIStatusError, RateLimitError

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

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="grok-4",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429, reintento {attempt + 1}, esperando {wait:.1f}s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}, reintentando en {wait:.1f}s")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Se agotaron los reintentos")

Los reintentos solo sirven para errores transitorios. En operaciones que ya produjeron efectos secundarios, usa primero una clave de idempotencia o consulta el estado para confirmar si la operación se ejecutó antes de decidir si la reenvías.

5. Timeouts y errores de conexión

En los timeouts hay que distinguir entre timeout de conexión y timeout de lectura. El de conexión suele indicar un problema de red, DNS o proxy; el de lectura puede deberse a una generación larga del modelo, una interrupción del streaming o un timeout de inactividad demasiado corto en el proxy.

Orden de diagnóstico:

  1. Usa curl para registrar time_namelookup, time_connect, time_appconnect y time_starttransfer, y observa en qué tramo se consume el tiempo.
  2. Confirma si el proxy tiene configurado un timeout de conexión o de inactividad demasiado corto.
  3. Para salidas largas, usa streaming y lee mientras se genera, en lugar de esperar la respuesta completa.
  4. Configura en el cliente timeouts de conexión y de lectura independientes; no uses un único timeout total muy grande como parche.
  5. En los reintentos tras un timeout, determina si la petición ya se ejecutó para evitar cargos o escrituras duplicadas.
export GROK_API_KEY="sk-tu-clave"

curl -o /dev/null -s \
  -w "code=%{http_code} dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n" \
  --max-time 120 \
  "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-4","messages":[{"role":"user","content":"Responde solo OK"}],"max_tokens":8}'

Si el DNS y la conexión son rápidos pero el primer byte tarda mucho, el problema probablemente esté en la generación o en el proveedor. Si el timeout ocurre ya en la fase de conexión, revisa primero la salida de red y el proxy; no toques el código de negocio.

6. Tabla de orden de diagnóstico

  1. Registra el código de estado, el tipo de error, el ID de la petición, el nombre del modelo y la hora del incidente.
  2. Para 401 y 403, revisa credenciales, estado de la cuenta y permisos; para 404, revisa ruta y nombre del modelo.
  3. Para 400, revisa parámetros, longitud de contexto, formato de imágenes y tamaño del cuerpo de la petición.
  4. Para 429, revisa cuota, concurrencia, claves compartidas y tormentas de reintentos.
  5. Para timeouts, analiza por capas: DNS, conexión, TLS, primer byte y tiempo total.
  6. Para 5xx, reintenta con retroceso; si persiste, contacta al proveedor e incluye el ID de la petición.
  7. Después de cada incidente, añade monitoreo y alertas; no esperes a que los usuarios reporten el problema.

Preguntas frecuentes

¿Cuál es la diferencia entre un 429 y un saldo insuficiente?

Un 429 indica que la petición superó un límite de velocidad o de cuota, y recargar no necesariamente lo resuelve. El saldo insuficiente suele devolver un error relacionado con la cuota o la facturación. Revisa el tipo de error y la factura antes de decidir si esperas, reduces la concurrencia o recargas.

¿Por qué hay más 429 después de añadir reintentos?

Puede que no haya retroceso, que la concurrencia sea demasiado alta o que varios servicios compartan una clave. Reintentar agresivamente a intervalos fijos convierte un límite pequeño en una tormenta de reintentos. Usa retroceso exponencial con jitter aleatorio y define un número máximo de reintentos.

El modelo existe, ¿por qué sigue devolviendo 404?

Comprueba primero si la URL base duplica /v1 y confirma que el endpoint es /chat/completions. Si la ruta es correcta, puede que la cuenta o el grupo no tengan habilitado ese modelo, o que el nombre tenga diferencias de mayúsculas o de sufijo de versión.

¿Se puede reenviar directamente después de un timeout?

Primero determina si la petición ya se ejecutó. Las consultas de solo lectura suelen poder reintentarse; las operaciones con escritura, cargos o efectos externos deben usar una clave de idempotencia o consultar el estado antes de repetirse.

¿Cómo distinguir un error del gateway de uno del proveedor?

Revisa el tipo de error y el ID de la petición, y después envía la misma petición contra la entrada del gateway y contra la entrada oficial. Así podrás separar rápidamente si el problema está en la clave, la red, la configuración del gateway o el servicio del proveedor.

Siguientes pasos

Crea primero una clave de prueba en ZSQH AI Gateway, ensaya una vez cada caso —401, 404, 429 y timeout— y después conecta el monitoreo de producción. La disponibilidad y los precios de los modelos se rigen por los precios de modelos.

Lecturas relacionadas: