Ante un error de Kimi API, mira primero tres cosas: el código de estado HTTP, error.type y request_id. Un mismo 429 puede ser sobrecarga del servidor, un límite de tasa de la organización o saldo insuficiente; un mismo 401 puede ser una clave mal escrita o una mezcla entre el sitio chino y el internacional. Clasifica primero y después cambia el código.

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

Nota: Moonshot y Kimi son marcas de sus respectivos titulares. Los tipos de error, las reglas de límite de tasa y el comportamiento de la interfaz pueden cambiar; este artículo toma como ejemplo la situación habitual de octubre de 2026 y la documentación oficial prevalece.

1. Tabla rápida de códigos de estado

Código Tipo de error Significado habitual Dirección de la solución
400 invalid_request_error Parámetro incorrecto, contexto demasiado largo, límite de salida excedido Corregir la solicitud
400 content_filter La entrada o la salida activó el filtro de seguridad Ajustar el prompt
401 invalid_authentication_error Clave inválida, región desajustada Corregir credenciales
401 incorrect_api_key_error Clave ausente o incorrecta Corregir credenciales
403 permission_denied_error Interfaz no habilitada, lista blanca de IP, saldo o permisos Revisar permisos y saldo
404 resource_not_found_error Nombre de modelo o ruta incorrectos Consultar la lista de modelos
429 engine_overloaded_error Sobrecarga del servidor Reintentar con retroceso
429 rate_limit_reached_error Concurrencia, RPM, TPM o TPD excedidos Bajar el ritmo o ampliar la cuota
429 exceeded_current_quota_error Deuda, saldo insuficiente, cupón vencido Recargar
499 client_closed_request El cliente o el proxy cerró la conexión antes de tiempo Revisar timeouts y streaming
500 server_error Error interno del servidor Reintentar con retroceso
503 server_unavailable Servicio temporalmente no disponible Reintentar con retroceso
504 Gateway Time-out Una solicitud larga esperó demasiado Cambiar a streaming

El saldo insuficiente puede aparecer como 403 o como 429 según la entrada, así que no decidas solo por el código de estado: guíate por error.type. En los logs registra al menos la hora, el código de estado, el tipo de error, el nombre del modelo y el request_id; nunca la clave completa ni contenido sensible.

2. 401: primero la región, después la clave

  1. Comprueba si una clave del sitio chino se está usando con la URL internacional, o al revés. Las cuentas, los saldos y las claves de ambos sitios son totalmente independientes.
  2. Comprueba si se mezclaron claves de distintas líneas de producto, por ejemplo la plataforma abierta, Kimi Code y la membresía.
  3. Revisa si la clave tiene espacios, saltos de línea o comillas sobrantes al principio o al final.
  4. Confirma que la variable de entorno realmente se cargó; puedes imprimir solo el prefijo para verificarlo.
  5. Verifica si la clave fue eliminada, rotada o no tiene permiso sobre el proyecto actual.
  6. Confirma que el encabezado es Authorization: Bearer <key> y que la ruta es /v1/chat/completions.
export MOONSHOT_API_KEY="tu-clave"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6",
    "max_completion_tokens": 64,
    "messages": [{"role": "user", "content": "Responde solo OK"}]
  }'

Si este comando devuelve 200, la clave, la región y el nombre del modelo están bien. Si sigue dando 401, prueba con una clave que sepas que funciona para distinguir si el problema es la clave o la configuración del gateway.

3. 404: el nombre del modelo y la base_url son los errores más comunes

Un 404 no significa necesariamente que el modelo se haya retirado. Estas son las cuatro causas habituales:

  • Al usar el SDK de OpenAI no se configuró base_url, la solicitud se envió a la dirección predeterminada de OpenAI y devolvió que el modelo no existe.
  • El nombre del modelo está mal escrito o se usó un modelo al que la cuenta no tiene acceso en este momento.
  • La ruta tiene un /v1 de más o de menos, o la interfaz de chat se escribió con otra ruta.
  • Los nombres de modelo y los permisos difieren entre el sitio chino y el internacional.

Primero consulta la lista de modelos con la misma clave para confirmar qué puede ver la cuenta:

curl "https://api.moonshot.cn/v1/models" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY"

No adivines un modelo que no aparece en la lista. La disponibilidad se rige por lo que devuelve realmente la cuenta y por los precios de modelos del sitio. Si la lista de modelos responde pero la interfaz de chat sigue dando 404, revisa si falta /v1 en la ruta y si el cliente está concatenando base_url con la ruta completa dos veces.

4. 429: tres tipos con tratamientos distintos

error.type Significado ¿Se puede reintentar? Tratamiento
engine_overloaded_error Sobrecarga del servidor Sí Retroceder según Retry-After y reducir la concurrencia
rate_limit_reached_error Concurrencia, RPM, TPM o TPD de la organización excedidos Parcialmente Bajar el ritmo, dividir claves, subir de nivel
exceeded_current_quota_error Deuda, saldo insuficiente, cupón vencido No Recargar o revisar la facturación

Cuando se excede el TPD, por lo general solo queda esperar al día siguiente o ampliar la cuota; seguir reintentando no aporta nada. Las solicitudes interrumpidas por un 429 normalmente no se cobran, pero sí se cobran cuando el reintento se completa; no reintentes sin límite por miedo al gasto ni asumas que la cuenta ya fue debitada solo por ver un 429. El SDK de OpenAI reintenta automáticamente de forma predeterminada, lo que puede convertir un 429 en varias solicitudes; en producción, configura max_retries de forma explícita y usa tu propia lógica de retroceso.

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="tu-clave",
    base_url="https://api.moonshot.cn/v1",
    max_retries=0,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="kimi-k2.6",
                messages=[{"role": "user", "content": prompt}],
                max_completion_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError as exc:
            body = exc.body or {}
            etype = (body.get("error") or {}).get("type", "")
            if etype == "exceeded_current_quota_error":
                raise RuntimeError("Saldo o cuota insuficientes; recarga primero")
            wait = min(2 ** attempt, 20) + random.random()
            print(etype, "espera", round(wait, 1), "segundos")
            time.sleep(wait)
    raise RuntimeError("Se agotaron los reintentos")

El reintento solo sirve para errores transitorios. En operaciones que ya produjeron efectos secundarios, usa primero una clave de idempotencia o una comprobación de estado para confirmar si se ejecutaron antes de decidir si reenviar.

5. Timeouts y 504

La generación de textos largos, el análisis de documentos extensos y los agentes de código son los casos más propensos a timeouts. El orden de tratamiento es:

  1. Cambia la solicitud sin streaming a stream=True para que la conexión reciba datos de forma continua.
  2. Define timeouts de conexión y de lectura razonables; no heredes los valores predeterminados del SDK.
  3. Revisa si el proxy corporativo, el gateway o las herramientas de enrutamiento local cortan la conexión antes de tiempo; estos casos pueden aparecer como 499.
  4. Usa max_completion_tokens para controlar la longitud de cada salida y divide las tareas ultralargas en segmentos.
  5. Registra el ID de solicitud y la duración de cada timeout para distinguir si la lentitud es del modelo, de la red o del gateway.
stream = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[{"role": "user", "content": "Escribe una lista de verificación de despliegue"}],
    max_completion_tokens=2048,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

El streaming no reduce el precio unitario, pero sí disminuye de forma notable el desperdicio de «esperar al timeout y reintentar». El timeout de conexión puede ser corto; el de lectura debe ajustarse al tiempo máximo de generación. En streaming no reutilices el timeout de lectura de una solicitud sin streaming, o el cliente cortará la conexión mientras el modelo todavía está generando con normalidad.

6. Tabla de orden de diagnóstico

  1. Registra el código de estado, error.type, request_id, nombre de modelo y hora del incidente.
  2. Para 401 y 403, revisa región, clave, línea de producto, permisos y saldo.
  3. Para 404, revisa base_url, nombre de modelo y permisos de la cuenta; valida con la lista de modelos.
  4. Para 400, revisa longitud de contexto, límite de salida, formato de archivo y filtro de contenido.
  5. Para 429, separa según error.type en sobrecarga, límite de tasa y falta de saldo.
  6. Para 499 y 504, revisa streaming, timeouts, proxies y persistencia de la conexión.
  7. Para 500 y 503, reintenta con retroceso; si persiste, envía el request_id al proveedor.
  8. 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 429 y 503?

Un 429 puede ser sobrecarga del servidor o un problema de cuota o saldo de la cuenta, así que primero hay que mirar error.type; un 503 indica que el servicio no está disponible temporalmente y suele resolverse con retroceso y reintento. En ambos casos, evita reintentar agresivamente a intervalos fijos.

Recargué y sigo recibiendo 401, ¿qué hago?

Confirma primero que la recarga y la clave pertenecen a la misma región y a la misma línea de producto. Prueba con una clave recién creada para descartar que la clave anterior se haya eliminado o que la variable de entorno esté en caché.

¿Qué error aparece cuando el contexto es demasiado largo?

Normalmente un 400 invalid_request_error, con un mensaje que menciona que la entrada de tokens es demasiado extensa. Acorta la entrada, recorta el historial o cambia a un modelo con mayor contexto.

¿Conviene activar los reintentos automáticos del SDK?

Se pueden activar, pero con un límite. El reintento predeterminado puede amplificar un 429; en producción se recomienda desactivar el reintento automático del SDK y aplicar tu propio retroceso exponencial por tipo de error, con alertas.

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

Lanza la misma solicitud por la conexión directa y por el gateway, y compara código de estado, error.type y request_id. Así puedes determinar rápidamente si la causa es el proveedor, la red, la clave o la configuración del gateway.

Próximos pasos

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

Lecturas relacionadas: