Los errores de la API de MiniMax se dividen en cuatro capas: el código de estado HTTP, el código de negocio dentro del cuerpo de la respuesta, el timeout de la capa de transporte y la anomalía del servicio de origen. Al diagnosticar, conviene separar las capas y luego ubicar el problema; no empieces cambiando el prompt ni el modelo. Muchos casos de «el modelo no sirve» terminan siendo una clave mal configurada, una dirección mezclada o un timeout demasiado corto.

Este artículo desglosa 401, 403, 404, 429, 5xx y timeouts, con causas, orden de diagnóstico y código de manejo de errores reutilizable. Los nombres de modelo, precios y cuotas se rigen por la documentación de MiniMax y los precios de modelos de este sitio.

Aviso: MiniMax es una marca de su titular. Los códigos de error, los niveles de límite de velocidad y el comportamiento de las interfaces pueden cambiar según la versión; este artículo toma como ejemplo las condiciones habituales de octubre de 2026 y la documentación de MiniMax prevalece.

1. Primero separa capas: estado, código de negocio y timeout

La documentación de códigos de error de MiniMax enumera los códigos de negocio por separado y pide incluir el trace_id de las cabeceras de respuesta al reportar un problema. La documentación de límites de velocidad, por su parte, limita en tres dimensiones: RPM, TPM y número de tareas concurrentes. Hay que revisar tanto la capa HTTP como la de negocio: algunas interfaces nativas pueden devolver HTTP 200 y colocar el error en base_resp dentro del cuerpo; la entrada compatible con OpenAI suele expresar el error con el código HTTP. Registra ambas capas para no dejar pasar ningún caso.

Síntoma Significado habitual Qué revisar primero Qué hacer
401, 1004, 2049 Fallo de autenticación o clave inválida Clave, cabecera Bearer, coincidencia de la dirección Probar una clave nueva con una solicitud mínima
403 Permisos, estado de la cuenta o restricción de entrada Permisos del modelo, verificación de identidad, cuota del gateway Contrastar con la consola y el cuerpo de la respuesta
404 Ruta o modelo inexistente Base URL, /v1, si el modelo fue retirado Consultar la lista de modelos del proveedor
400, 2013, 1039 Parámetros incorrectos o tokens excedidos thinking, temperature, max_tokens Ajustar los parámetros según la documentación
429, 1002, 2045, 1041, 2056 Límite de velocidad, concurrencia o ventana del plan RPM, TPM, claves compartidas, picos de tráfico Retroceso, cola y separación de claves
1008 Saldo insuficiente Saldo de la cuenta, cuota de la suscripción Recargar o cambiar de forma de pago
Timeout, 1001 Timeout de conexión o de lectura Red, proxy, salida larga, configuración de streaming Configurar timeouts por capa
5xx, 1024, 1033 Anomalía del servicio de origen Estado del servicio, si la solicitud se puede reintentar Reintentar con retroceso y límite

En los registros hay que anotar al menos la hora, el código de estado, el código de negocio, el nombre del modelo, la duración y el trace_id. No registres la clave completa ni imprimas el texto del usuario entero en el log.

2. 401 y 403: primero autenticación, después permisos

El 401 indica que la identidad no pasó la verificación y normalmente no tiene relación con la capacidad del modelo. Revisa en este orden:

  • Si la cabecera es Authorization: Bearer <key> y no un esquema de autenticación personalizado.
  • Si la clave tiene espacios, saltos de línea o comillas delante o detrás; copiarla desde una ventana de chat es la causa más frecuente.
  • Si la variable de entorno se cargó realmente; puedes imprimir solo el prefijo para confirmarlo.
  • Si la clave fue eliminada, rotada o desactivada.
  • Si la Base URL y la clave pertenecen a la misma plataforma; una clave de MiniMax con la dirección de un gateway produce 401.
  • Si un proxy inverso sobrescribe o descarta la cabecera Authorization.
  • Si se mezclan claves de suscripción M Plan con claves de pago por uso. La documentación de MiniMax indica que son independientes y que las cuotas no se pueden usar indistintamente.

El 403 apunta más a permisos o al estado de la cuenta: si el modelo está habilitado, el estado de verificación de la cuenta, si la entrada actual permite ese modelo, y la cuota o el control de riesgo del gateway. El significado del 403 puede variar entre entradas; revisa primero el mensaje de error y la marca de origen en el cuerpo. Si la misma solicitud funciona en la entrada de MiniMax y devuelve 403 en el gateway, revisa primero la configuración y la cuota del gateway.

3. 404: la Base URL y el nombre del modelo son los errores más frecuentes

Un 404 no suele significar «la interfaz está caída», sino que la solicitud llegó a una ruta o a un modelo inexistente. Causas comunes:

  • La Base URL corresponde a otro proveedor, o tiene /v1 de más o de menos.
  • El SDK añade /chat/completions automáticamente y la ruta escrita a mano lo añade otra vez.
  • El nombre del modelo usa una versión antigua ya retirada, o difiere en mayúsculas o sufijo.
  • Se mezclan la dirección de MiniMax y la del gateway, que tienen reglas de ruta distintas.
  • Una regla de reescritura del proxy inverso rompe la ruta.

La lista de modelos de MiniMax muestra que los modelos de texto históricos como M2.5 y M2.7 entraron en proceso de retiro: dejan de estar disponibles para usuarios nuevos desde el 19 de octubre de 2026 y se planea su retiro completo para el 18 de noviembre de 2026. Los modelos de texto que figuran actualmente en la documentación son MiniMax-M3 y MiniMax-M3.1-Flash. Seguir usando nombres antiguos puede producir 404 o errores de negocio. Antes de migrar, verifica el nombre en la lista de modelos del proveedor y en la página de precios del sitio.

4. 429: el límite de velocidad no es saldo insuficiente

El 429 indica que la solicitud superó un límite de velocidad, concurrencia o cuota. La documentación de límites de MiniMax restringe por RPM (solicitudes por minuto), TPM (tokens de entrada y salida por minuto) y número de tareas concurrentes; la cuenta principal y las subcuentas comparten el límite. Los niveles predeterminados que la documentación indica actualmente para M3/M3.1-Flash son: 20 RPM para usuarios gratuitos y 200 RPM para usuarios con recarga, con TPM de 1 millón y 10 millones respectivamente; la consola prevalece.

Escenarios habituales:

  • Varios servicios comparten una clave y compiten por la misma cuota.
  • Las tareas por lotes arrancan al mismo tiempo en punto, generando un pico de tráfico.
  • Los reintentos no tienen retroceso y cada fallo genera más solicitudes, formando una tormenta de reintentos.
  • Las salidas largas o las tareas de razonamiento ocupan recursos y reducen el espacio de concurrencia.
  • La ventana del plan vence y se activa la restricción de recursos de M Plan.

Cómo responder: separa claves por proyecto; envía las tareas por lotes a una cola para suavizar el ritmo; añade a los reintentos un límite, retroceso exponencial y jitter aleatorio; limita por separado las tareas de salida larga; y si la respuesta trae Retry-After, respétalo. Cuando recibas un 429, no aumentes la concurrencia: primero aplana la carga.

5. Timeouts y 5xx: distingue conexión, primer token y lectura

Un timeout no equivale a servicio no disponible; primero hay que ubicar en qué tramo se queda:

  • Timeout de conexión: DNS, salida de red o proxy inaccesible; revisa la red y el proxy.
  • Primer token muy lento: cola en el origen o prompt demasiado largo; acorta la entrada, distribuye la carga o usa un modelo más ligero.
  • Timeout de lectura: salida demasiado larga o razonamiento prolongado; aumenta el timeout de lectura y limita la salida.
  • Interrupción de streaming: fluctuación de red o corte del proxy; el cliente debe admitir reconexión y deduplicación.
  • Timeout de tareas asíncronas: en video y voz hay que distinguir «tarea en cola» de «solicitud agotada»; consulta por task_id y no envíes la tarea dos veces.

Los 5xx y los códigos de negocio 1000, 1024 y 1033 suelen indicar una anomalía o sobrecarga del servicio de origen. Estos errores admiten reintentos con retroceso, pero con un límite. En operaciones con efectos secundarios, usa primero una clave de idempotencia o consulta el estado para confirmar si la acción ya se ejecutó. Los enlaces de descarga del audio asíncrono tienen vigencia (la documentación actual indica 9 horas); si expiran, hay que solicitarlos de nuevo.

6. Código de manejo de errores: retroceso, trace_id y registros

import logging
import os
import random
import time

import httpx
from openai import (
    APITimeoutError,
    APIStatusError,
    AuthenticationError,
    OpenAI,
    RateLimitError,
)

log = logging.getLogger("minimax")
client = OpenAI(
    api_key=os.environ["MINIMAX_API_KEY"],
    base_url=os.environ.get("MINIMAX_BASE_URL", "https://api.minimax.cn/v1"),
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
    max_retries=0,  # Desactiva los reintentos automáticos del SDK; la lógica siguiente los controla
)

def trace_id(exc: Exception) -> str:
    response = getattr(exc, "response", None)
    headers = getattr(response, "headers", {}) or {}
    return headers.get("trace_id") or headers.get("x-request-id") or "-"

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["MINIMAX_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content or ""
        except AuthenticationError as exc:
            log.error("Fallo de autenticación status=%s trace_id=%s", exc.status_code, trace_id(exc))
            raise
        except RateLimitError as exc:
            wait = min(2 ** attempt, 30) + random.uniform(0, 1)
            log.warning("Límite de velocidad attempt=%s wait=%.1fs trace_id=%s",
                        attempt + 1, wait, trace_id(exc))
            time.sleep(wait)
        except APITimeoutError as exc:
            wait = min(2 ** attempt, 15) + random.uniform(0, 1)
            log.warning("Timeout de solicitud attempt=%s wait=%.1fs trace_id=%s",
                        attempt + 1, wait, trace_id(exc))
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 30) + random.uniform(0, 1)
                log.warning("Error del origen status=%s attempt=%s wait=%.1fs trace_id=%s",
                            exc.status_code, attempt + 1, wait, trace_id(exc))
                time.sleep(wait)
                continue
            log.error("Error del cliente status=%s detail=%s trace_id=%s",
                      exc.status_code, exc, trace_id(exc))
            raise
    raise RuntimeError("Se agotaron los reintentos; contacta al proveedor con el trace_id")

print(ask("Explica en una frase qué es un límite de velocidad de API"))

Este código hace cuatro cosas: distingue errores reintentables de los que no lo son, aplica retroceso exponencial con jitter, escribe el trace_id en el registro y trata los 5xx por separado. No sustituye el diseño idempotente: las solicitudes con efectos secundarios deben consultar el estado primero.

7. Registros y monitoreo: los campos mínimos

  • Hora y proyecto: para ubicar picos y alcance del impacto.
  • Código de estado HTTP y código de negocio: para distinguir autenticación, límite, parámetros y errores del origen.
  • trace_id o x-request-id: la evidencia clave para que el proveedor investigue.
  • Dirección de la interfaz y nombre del modelo: para saber si el problema apareció tras cambiar de modelo o de entrada.
  • Tokens de entrada y salida: para analizar costo y solicitudes largas.
  • Duración, número de reintentos y concurrencia: para detectar latencia de cola y tormentas de reintentos.
  • Alias de la clave: para estadísticas por proyecto; nunca registres la clave en texto plano.

El monitoreo debe contar al menos cada hora los 401, 403, 404, 429, timeouts y 5xx. Si la tasa de error se dispara, mira primero si se concentra en un proyecto, una clave o un modelo, y luego decide si reducir la concurrencia, cambiar de canal o revertir la versión.

8. Lista de verificación antes de contactar al soporte

  1. Hora del incidente, zona horaria, duración y qué interfaces se vieron afectadas.
  2. Código HTTP, código de negocio y mensaje de error completo; anonimiza antes lo sensible.
  3. El trace_id de las cabeceras y el x-request-id que pueda añadir el gateway.
  4. Dirección de la interfaz, nombre del modelo, versión del SDK y parámetros de la solicitud.
  5. Un curl mínimo reproducible, sin datos del negocio ni información personal.
  6. Si es conexión directa o entrada por gateway, y si se usa una clave de pago por uso o una clave M Plan.
  7. Concurrencia del mismo periodo, RPM/TPM, número de reintentos y si hubo picos de tráfico.
  8. Si se cambió de modelo, se actualizó el SDK o se modificó el proxy o la configuración del gateway recientemente.
  9. Si es un 1008, adjunta una captura del saldo o del estado del plan, también anonimizada.

Reunir todo esto en un solo mensaje ahorra mucho más tiempo que enviar solo «hay un error». El proveedor suele pedir el trace_id y la ventana de tiempo como primera información.

Preguntas frecuentes

¿El 429 significa saldo insuficiente?

No. El 429 indica que la solicitud superó un límite de velocidad, concurrencia o cuota; el saldo insuficiente corresponde habitualmente al código de negocio 1008. Revisa primero la concurrencia, las claves compartidas y los picos de tráfico.

¿Por qué hay errores aunque el HTTP sea 200?

Algunas interfaces nativas de MiniMax expresan el error de negocio en base_resp.status_code dentro del cuerpo, mientras la capa HTTP sigue en 200. Con esas interfaces, el código no debe mirar solo el estado HTTP: también debe analizar el cuerpo. La entrada compatible con OpenAI suele devolver directamente el código de error HTTP.

¿Dónde se obtiene el trace_id?

La documentación de códigos de error de MiniMax indica leerlo de las cabeceras de respuesta. Al pasar por un gateway, este puede devolver además un x-request-id; registra ambos.

¿Se puede reintentar un timeout sin límite?

No. Los reintentos deben tener un máximo, retroceso y alertas; además, un timeout puede significar que la solicitud ya se ejecutó en el origen. En operaciones con efectos secundarios, confirma el estado antes de reenviar.

¿Qué hago si aparece un 404 después de cambiar de modelo?

Revisa primero si el nombre del modelo fue retirado y luego si la Base URL tiene /v1 de más o de menos. Los modelos de texto históricos de MiniMax se están retirando por etapas; no supongas que un nombre antiguo sigue disponible. Rígete por la lista de modelos del proveedor y la página de precios del sitio.

Próximos pasos

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

Lecturas relacionadas: