Los errores de la API de DeepSeek se dividen en cuatro grandes grupos: autenticación, ruta y nombre de modelo, límites de velocidad y timeouts. El orden correcto de diagnóstico es: mirar primero el código de estado HTTP y el tipo de error, después el ID de solicitud y la reproducción mínima, y solo al final cambiar el prompt o el modelo. Si se invierte el orden, es fácil confundir un problema de configuración con una limitación de capacidad del modelo.

Este artículo separa los cuatro casos —401, 404, 429 y timeout— y ofrece causas, pasos de revisión y código de retroceso reutilizable. Los modelos y precios se rigen por los precios de modelos de este sitio.

Nota: DeepSeek es una marca de su titular. Los tipos de error, los criterios de limitación y el comportamiento de la interfaz pueden cambiar con las versiones; este artículo describe la situación habitual en octubre de 2026 y la documentación oficial prevalece.

1. Distingue primero las cuatro categorías

Estado o síntoma Significado habitual Causa típica Orden de actuación
401 Fallo de autenticación Clave incorrecta, falta el encabezado Bearer, clave desactivada Corregir primero las credenciales
404 Ruta o modelo inexistente Base URL incorrecta, nombre de modelo antiguo, ruta duplicada Revisar dirección y nombre de modelo
429 Límite de velocidad o cuota restringida Aumento brusco de concurrencia, clave compartida, tormenta de reintentos Retroceso y reducción de concurrencia
Timeout Timeout de conexión o de lectura Red, salida larga, modelo de razonamiento, proxy Diagnóstico por capas
400 Parámetros o contexto incorrectos Contexto excedido, formato inválido Cuantificar y dividir
5xx Error del servicio del proveedor Falla o sobrecarga del servidor Retroceso y cambio de canal

En los registros guarda como mínimo la hora, el código de estado, el tipo de error, el nombre de modelo, la latencia y el ID de solicitud. No registres la clave completa ni imprimas el texto original del usuario en los logs.

2. 401: revisa primero los encabezados y después la clave

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. Revisa en este orden:

  1. El encabezado debe ser Authorization: Bearer <key>, no otro esquema de autenticación.
  2. Comprueba que la clave no tenga espacios, saltos de línea o comillas de más antes o después. Copiarla desde una ventana de chat es la causa más habitual.
  3. Confirma que la variable de entorno se carga de verdad; puedes imprimir solo el prefijo para verificarlo.
  4. Comprueba si la clave fue eliminada, rotada o desactivada.
  5. La Base URL y la clave deben pertenecer a la misma plataforma; una clave oficial con la dirección de un gateway produce un 401.
  6. Revisa si el proxy inverso sobrescribe o descarta el encabezado Authorization.
export DEEPSEEK_API_KEY="sk-tu-clave"

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

Si este comando devuelve 200, la clave, la Base URL y el nombre de modelo son correctos. Si sigue devolviendo 401, prueba con una clave nueva y una solicitud mínima para distinguir si el problema está en la clave o en la configuración del proxy o del gateway.

3. 404: los errores más frecuentes están en la dirección y el nombre del modelo

Un 404 normalmente no significa «la interfaz está caída», sino que la solicitud llegó a una ruta o a un modelo que no existe. Causas habituales:

  • La Base URL apunta a otro proveedor o tiene un /v1 de más o de menos.
  • El SDK añade /chat/completions automáticamente y, al escribir la ruta a mano, se añade otra vez.
  • El nombre de modelo corresponde a una versión retirada, o no coincide en mayúsculas, minúsculas o sufijo.
  • Se mezclan direcciones de gateway y direcciones oficiales, que tienen reglas de ruta distintas.
  • Las reglas de reescritura del proxy inverso alteran la ruta.

Para diagnosticar, llama primero a la dirección completa con curl y revisa el mensaje de error del cuerpo; después compara la Base URL y el nombre de modelo con la página de precios del sitio. No codifiques varias direcciones en el código: configúralas por entorno para que la dirección de pruebas no llegue a producción.

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

Un 429 indica que la solicitud superó un límite de velocidad, concurrencia o cuota. DeepSeek puede limitar o poner en cola solicitudes en horas punta; el criterio exacto se rige por la documentación oficial. Escenarios habituales:

  • Varios servicios comparten una clave y compiten por la misma cuota.
  • Las tareas por lotes arrancan a la misma hora en punto y generan un pico de tráfico.
  • Los reintentos no aplican retroceso y, cuanto más fallan, más solicitudes envían, creando una tormenta.
  • Las tareas de salida larga o de razonamiento consumen más recursos y dejan menos margen para la concurrencia.
Síntoma Posible causa Tratamiento
429 concentrados en horas punta Carga del proveedor o pico de tráfico Colas, envío suavizado, escalonar horarios
429 con una clave usada por varios servicios Cuota compartida Separar claves por proyecto
Empeora después de reintentar Reintentos sin retroceso Retroceso exponencial con jitter
Las solicitudes largas reciben 429 primero Alto consumo de tokens de salida Reducir max_tokens o la concurrencia 
import random
import time
from openai import OpenAI, RateLimitError, APITimeoutError, APIStatusError

client = OpenAI(
    api_key="sk-tu-clave",
    base_url="https://api.deepseek.com",
    max_retries=0,  # desactiva los reintentos automáticos del SDK para no duplicarlos
)

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

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

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

5. Timeout: distingue conexión, lectura y streaming

Un timeout no equivale a que el servicio esté caído; primero hay que localizar en qué tramo se bloquea:

Síntoma Posible causa Tratamiento
Timeout de conexión DNS, salida de red o proxy inaccesible Revisar red y proxy, cambiar de ruta
Primer token muy lento Cola del proveedor, prompt demasiado largo Acortar la entrada, escalonar, usar un modelo ligero
Timeout de lectura Salida demasiado larga, modelo de razonamiento que piensa mucho Aumentar el timeout de lectura, limitar la salida
Streaming interrumpido Inestabilidad de red, corte del proxy Soportar reconexión y guardar lo recibido
Todos los servicios fallan a la vez Salida local o fallo del proveedor Cambiar al canal de respaldo y revisar el estado del servicio 
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="sk-tu-clave",
    base_url="https://api.deepseek.com",
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
)

Los timeouts de conexión y de lectura deben configurarse por separado. Si todos se ponen en un valor muy alto, una falla puede bloquear el pool de hilos; si se ponen demasiado bajos, se cancelan tareas largas que eran normales. Configurarlos según el tipo de tarea es la opción más segura.

6. Tabla de orden de diagnóstico

  1. Registra el código de estado, el tipo de error, el ID de solicitud, el nombre de modelo y la hora.
  2. Para 401, revisa la clave, los encabezados, las variables de entorno y la coincidencia de plataforma.
  3. Para 404, revisa la Base URL, la concatenación de rutas y el nombre de modelo.
  4. Para 400, revisa los parámetros, la longitud del contexto y el formato de imágenes o archivos.
  5. Para 429, revisa la concurrencia, las claves compartidas, la estrategia de reintentos y las horas punta.
  6. Para timeouts, revisa DNS, proxy, longitud de salida y configuración del timeout de lectura.
  7. Para 5xx, reintenta primero con retroceso; si persiste, contacta al proveedor e incluye el ID de solicitud.
  8. Después de cada incidente, añade monitoreo y alertas; no esperes a que el usuario lo reporte.

7. Monitoreo y registros

Campo Utilidad
Hora y proyecto Localizar picos y alcance del impacto
Código de estado y tipo de error Distinguir autenticación, límites y errores del proveedor
ID de solicitud Evidencia clave para que el proveedor investigue
Nombre y versión del modelo Determinar si apareció tras un cambio de modelo
Tokens de entrada y salida Analizar costos y solicitudes largas
Latencia y número de reintentos Detectar latencia de cola y tormentas de reintentos

Monitorea al menos cada hora el número de 401, 404, 429, timeouts y 5xx. Si la tasa de error se dispara, revisa primero si se concentra en un proyecto, una clave o un modelo, y después decide si reducir la concurrencia, cambiar de canal o revertir la versión.

Preguntas frecuentes

¿Un 429 significa saldo insuficiente?

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

¿Cuál es la causa más frecuente de un 404?

Una Base URL incorrecta, una ruta concatenada dos veces o un nombre de modelo caducado. Llama primero a la dirección completa con curl y compara el nombre de modelo con la página de precios; normalmente se localiza en pocos minutos.

¿Conviene 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 proveedor. En operaciones con efectos secundarios, confirma el estado antes de decidir si reenviar.

¿Qué hago si se interrumpe una respuesta en streaming?

Registra el contenido recibido y el punto de interrupción, y determina si fue inestabilidad de red, corte del proxy o timeout del proveedor. El cliente debe soportar reconexión y deduplicación; no guardes un contenido a medias como si fuera un resultado completo.

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

Conserva el ID de solicitud y el tipo de error, y envía la misma solicitud al punto de entrada oficial y al gateway. Así puedes distinguir rápidamente si el problema es de clave, de red, de configuración del gateway o del proveedor.

Próximos pasos

Crea una clave de prueba en ZSQH AI Gateway, practica 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: