La mayoría de los errores de la API de Mistral no se deben a la capacidad del modelo, sino a las credenciales, la ruta, los parámetros, los límites de velocidad o la red. El orden de diagnóstico debería ser: primero el código de estado HTTP y el tipo de error, después el ID de solicitud de la respuesta y una reproducción mínima, y solo al final ajustar el prompt o cambiar de modelo. Si inviertes el orden, es fácil confundir un error de configuración con un modelo que «no sirve».

Este artículo desglosa 401, 403, 404, 422, 429, 5xx y los timeouts, y ofrece código de reintento, control de concurrencia, campos de registro y una lista para abrir un ticket de soporte. Las cuotas concretas, los mensajes de error y el comportamiento de la interfaz se rigen por la documentación y la consola de Mistral.

Nota: Mistral es una marca de su titular. Este artículo solo discute aspectos técnicos; los códigos de error, los criterios de límite y el comportamiento de la interfaz pueden cambiar según la versión, y prevalecen la documentación y la consola oficiales.

1. Mira primero el código de estado, no el prompt

Estado o síntoma Significado habitual Causa típica Orden de acción
401 No pasó la autenticación Clave ausente, formato incorrecto o caducada Corregir las credenciales primero
403 Sin permisos Modelo no habilitado, rol de espacio de trabajo insuficiente, restricción regional Revisar cuenta y permisos
404 Ruta o modelo inexistente URL base incorrecta, ruta duplicada, modelo retirado Revisar dirección y nombre del modelo
422 Semántica de la solicitud inválida Campos faltantes, tipo incorrecto, parámetro no soportado Leer el detalle y corregir parámetros
429 Se alcanzó el límite o la cuota Aumento repentino de concurrencia, clave compartida, tormenta de reintentos Aplicar retroceso y bajar la concurrencia
5xx Falla del servicio upstream Sobrecarga, error del gateway, falla temporal Reintento limitado y cambio de canal
Timeout Timeout de conexión o de lectura Red inestable, salida demasiado larga, timeout de inactividad del proxy Localizar por capas

En los registros anota al menos la hora, el código de estado, el tipo de error, el nombre del modelo, la duración y el ID de solicitud. No registres la clave completa ni el texto original del usuario.

2. 401 y 403: autenticación y permisos

Un 401 indica que la identidad no se validó y normalmente no tiene relación con la capacidad del modelo ni con el saldo. Revisa en este orden:

  • Que el encabezado sea Authorization: Bearer <key>, no un campo personalizado ni una autenticación antigua.
  • Que la clave no tenga espacios, saltos de línea o comillas extra; copiarla desde una ventana de chat es la causa más común.
  • Que la variable de entorno se haya cargado realmente; puedes imprimir solo el prefijo para confirmarlo, nunca la clave completa.
  • Que la clave no haya sido eliminada, rotada o desactivada, y que el entorno de prueba no esté usando la clave de producción.
  • Que la URL base y la clave pertenezcan a la misma plataforma; usar la clave de A en la plataforma B produce un 401 directo.
  • Que el proxy inverso o el SDK no sobrescriban ni descarten el encabezado Authorization.

Un 403 significa «identidad reconocida, pero sin permiso». Las causas habituales son que la cuenta o el espacio de trabajo no tenga permiso para invocar ese modelo, que el rol sea insuficiente, que el modelo no esté abierto en la región actual o que la solicitud llegue a una interfaz no habilitada. Revisa la lista de modelos y los permisos de miembros en la consola y, después, llama con la misma clave a un modelo que ya sepas que funciona, como control.

3. 404 y 422: dirección, nombre del modelo y parámetros

Un 404 no suele significar que la interfaz esté caída, sino que la solicitud llegó a una ruta o un modelo inexistente. Las causas comunes son una URL base mal escrita, un /v1 de más o de menos, el SDK que añade una ruta y el código manual que la añade otra vez, un nombre de modelo antiguo ya retirado y un gateway sin la ruta configurada. Envía primero una solicitud mínima a la dirección completa, revisa el mensaje de error del cuerpo y compara después con la lista de modelos de la consola.

Un 422 indica que el formato es correcto pero la semántica no es válida. Aparece cuando falta un campo obligatorio, el tipo de un campo no coincide, messages está vacío, max_tokens supera el rango, se envía un parámetro que el modelo actual no admite o el JSON está dañado. El cuerpo de la respuesta suele indicar el campo y el motivo; lee detail o error, corrige según la indicación y no reintentes a ciegas.

4. 429: límites, concurrencia y tormenta de reintentos

Un 429 indica que la solicitud superó el límite de velocidad, de concurrencia o de cuota, y no equivale a saldo insuficiente. Escenarios habituales:

  • Varios servicios comparten una clave y se disputan la cuota.
  • Las tareas por lotes arrancan todas a la hora en punto y crean un pico de tráfico.
  • Los reintentos no aplican retroceso y cuantos más fallos, más solicitudes se envían, hasta formar una tormenta.
  • Las salidas largas o el streaming ocupan la conexión mucho tiempo y dejan menos espacio para la concurrencia.
  • No se separan prueba, preproducción y producción, y el tráfico de prueba agota la cuota de producción.

Al diagnosticar, revisa si la respuesta trae una indicación como Retry-After; si la trae, espera lo que indique. Si no, usa retroceso exponencial con jitter aleatorio. Baja también la concurrencia, añade colas y un cubo de tokens a las tareas por lotes y limita por modelo, por clave y por entorno. No trates los reintentos como una ampliación de capacidad: solo absorben fluctuaciones breves, no resuelven una falta de capacidad sostenida.

5. 5xx y timeouts: upstream, red y streaming

Los 5xx incluyen 500, 502, 503 y 504, y pueden deberse a sobrecarga del upstream, fallo de reenvío del gateway o una falla temporal. Primero delimita el alcance: si fallan todos los modelos o solo uno, una región o un enlace. Un 5xx breve admite reintentos limitados; un 5xx persistente exige bajar la concurrencia, cambiar a un canal de respaldo y conservar el ID de solicitud para consultar al proveedor.

Los timeouts deben separarse en timeout de conexión, de lectura y de inactividad en streaming. El de conexión suele relacionarse con la red, el DNS o el proxy; el de lectura es común con salidas largas, razonamiento complejo y colas del upstream; en streaming, además, el timeout de inactividad del proxy puede cortar la conexión. El cliente debe fijar explícitamente timeouts de conexión y lectura, y en streaming definir un timeout de inactividad y una estrategia de reconexión. Para solicitudes con efectos secundarios, no reenvíes directamente después de un timeout: confirma primero si el upstream ya la ejecutó.

6. ID de solicitud y registros: la base del diagnóstico

El ID de solicitud es el punto de anclaje para diagnosticar entre equipos. La respuesta o el cuerpo del error suelen incluir un identificador, a menudo en x-request-id. Tanto en conexión directa como a través de un gateway, regístralo y vincúlalo con el número de pedido del negocio.

Se recomienda que el registro incluya: hora, ID de solicitud, código de estado, tipo de error, nombre del modelo, tokens de entrada y salida, duración, número de reintentos, si fue streaming y el canal upstream. El contenido del usuario debe desidentificarse o guardarse solo como resumen, y de la clave se registra únicamente el prefijo. Una captura de error sin ID de solicitud dificulta mucho que el equipo de soporte localice la solicitud concreta.

7. Reintentos y retroceso: qué reintentar y cómo

Un reintento debe cumplir tres condiciones: el error es recuperable, la solicitud es repetible y el reintento tiene un límite. No reintentes 401, 403, 404 ni 422: son problemas de configuración o de parámetros y reintentar solo hace perder tiempo. Los 429, los 5xx y los timeouts admiten reintentos acotados, y conviene respetar Retry-After.

El siguiente ejemplo reúne los estados reintentables, el retroceso exponencial, el jitter aleatorio y el registro del ID de solicitud. En producción también deberías añadir un cortacircuitos, reporte de métricas y una decisión de reenvío basada en la idempotencia del negocio.

import os
import random
import time

import requests

API_KEY = os.environ["MISTRAL_API_KEY"]
URL = "https://api.mistral.ai/v1/chat/completions"
RETRY_STATUS = {429, 500, 502, 503, 504}


def wait_seconds(resp, attempt):
    value = resp.headers.get("Retry-After") if resp is not None else None
    if value:
        try:
            return min(float(value), 60.0)
        except ValueError:
            pass
    return min(2 ** attempt + random.random(), 30.0)


def chat(payload, max_retries=4):
    last_error = None
    for attempt in range(max_retries + 1):
        try:
            resp = requests.post(
                URL,
                headers={
                    "Authorization": f"Bearer {API_KEY}",
                    "Content-Type": "application/json",
                },
                json=payload,
                timeout=(5, 60),  # conexión 5 s, lectura 60 s
            )
        except requests.Timeout as exc:
            last_error = exc
            if attempt == max_retries:
                break
            time.sleep(wait_seconds(None, attempt))
            continue

        request_id = resp.headers.get("x-request-id", "unknown")
        if resp.status_code == 200:
            return resp.json()

        if resp.status_code in RETRY_STATUS:
            last_error = RuntimeError(
                f"HTTP {resp.status_code}, request_id={request_id}"
            )
            if attempt == max_retries:
                break
            time.sleep(wait_seconds(resp, attempt))
            continue

        # Reintentar 401/403/404/422 no aporta: es un problema de configuración o de parámetros
        raise RuntimeError(
            f"HTTP {resp.status_code}, request_id={request_id}, "
            f"body={resp.text[:500]}"
        )

    raise RuntimeError(f"retry exhausted: {last_error}")

Además de los reintentos, hay que gobernar la concurrencia: un semáforo por modelo, una cola para las tareas por lotes, claves distintas por entorno y alertas sobre la proporción de 429. Trata los límites como un problema de capacidad, no como un error ocasional.

8. Lista para el ticket de soporte

Antes de contactar al soporte de la plataforma, organiza la información según esta lista; el tiempo de diagnóstico se reduce de forma notable:

  1. Hora y rango de ocurrencia, con zona horaria, y si el fallo es continuo o intermitente.
  2. ID de solicitud completo, código de estado y cuerpo del error, con los datos sensibles desidentificados.
  3. Dirección de la solicitud, nombre del modelo, si usa streaming y si emplea llamadas a herramientas o salida estructurada.
  4. Una solicitud mínima reproducible, sin campos ajenos al negocio y con los parámetros necesarios.
  5. Alcance: cuántos usuarios, qué regiones, qué redes y si fallan todos los modelos.
  6. Cambios recientes: rotación de claves, actualización de modelos o ajustes de proxy o gateway.
  7. Diagnósticos ya realizados y sus resultados, incluidas las comparaciones al cambiar de clave, modelo, red o concurrencia.

Preguntas frecuentes

Cambié a una clave nueva y el 401 continúa, ¿qué hago?

Confirma que la clave nueva pertenece a la plataforma de la URL base actual y revisa si la variable de entorno se cargó y si el proxy transmite el encabezado Authorization. Envía la solicitud mínima a la entrada oficial y a la del gateway por separado; así distingues rápido si el problema es la clave o el enlace.

¿Un 429 significa saldo insuficiente?

No. Un 429 indica que se superó el límite de velocidad, concurrencia o cuota; el saldo insuficiente suele devolver otro error o explicarlo en el cuerpo. Revisa primero la concurrencia, las claves compartidas y la estrategia de reintentos, y después el estado de la cuenta.

¿Cuál es la diferencia entre 422 y 400?

Ambos pueden ser problemas de parámetros, pero el 422 enfatiza que el formato es correcto y la semántica no es válida, por ejemplo un tipo de campo incorrecto o un campo obligatorio ausente. En la práctica, guíate por la indicación del campo en el cuerpo y no adivines solo por el código.

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

Depende de si la solicitud tiene efectos secundarios. Una consulta pura admite reintentos limitados; para crear un pedido, cobrar o enviar un mensaje, confirma primero si el upstream ya la ejecutó o usa una clave de idempotencia. El timeout solo indica que el cliente no recibió el resultado, no que el upstream no la haya procesado.

¿Qué preparar antes de abrir un ticket?

Prepara el rango de tiempo, el ID de solicitud, el código de estado, el cuerpo del error, el nombre del modelo, una reproducción mínima y el alcance. Añade los cambios recientes y los diagnósticos ya hechos para que el equipo de soporte localice el enlace concreto.

Siguiente paso

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

Lecturas relacionadas: