Verificado el 20 de julio de 2026. Esta guía explica los códigos HTTP documentados por DeepSeek y cómo responder a cada uno sin confundir un fallo de la solicitud con una interrupción del modelo.
Nota de evidencia e independencia: DeepSeek-Espanol.chat es un sitio independiente y no pertenece a DeepSeek ni cuenta con su respaldo. Las causas de la tabla proceden de la documentación oficial de códigos de error de DeepSeek. Las recomendaciones adicionales de registro y reintento están identificadas como prácticas del cliente; no son garantías del proveedor. No se afirma que exista una incidencia activa.
Respuesta rápida
Corrige la solicitud antes de repetir un error 400 o 422, revisa la clave ante un 401 y comprueba el saldo ante un 402. Un 429 exige reducir las solicitudes simultáneas y volver a intentarlo cuando haya capacidad. Los errores 500 y 503 son problemas del servicio: espera brevemente, consulta el estado oficial y reintenta de forma limitada. No existe un cambio local que garantice resolver un 500 o un 503.
| Código | Significado documentado | Primera acción | ¿Reintentar sin cambios? |
|---|---|---|---|
400 | Formato no válido | Leer el cuerpo del error y corregir el JSON | No |
401 | Fallo de autenticación | Comprobar la clave y la cabecera Bearer | No |
402 | Saldo insuficiente | Consultar el saldo y recargar | No |
422 | Parámetros no válidos | Corregir nombres, tipos o valores | No |
429 | Límite alcanzado | Reducir concurrencia | Sí, con espera |
500 | Error interno del servidor | Esperar y reintentar | Sí, de forma limitada |
503 | Servidor sobrecargado | Esperar y revisar el estado | Sí, de forma limitada |
Prueba primero una solicitud mínima
Antes de depurar un framework, un agente o una cadena de herramientas, reduce la llamada a una petición directa. El centro general de esta web explica la configuración en DeepSeek API; aquí solo se usa una solicitud mínima para aislar el error. La clave se lee desde una variable de entorno y no debe escribirse en el repositorio.
curl https://api.deepseek.com/chat/completions \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-pro",
"messages": [
{"role": "user", "content": "Responde solo: OK"}
],
"thinking": {"type": "disabled"},
"stream": false
}'Si esta llamada funciona, el problema probablemente está en los campos añadidos por la aplicación, en la serialización o en el historial enviado. Si falla, conserva el estado HTTP y el cuerpo de la respuesta, pero elimina la clave, el contenido sensible y los datos personales antes de compartir el registro.
Error 400: formato no válido
DeepSeek define el 400 como un cuerpo con formato no válido. Revisa que el documento sea JSON válido, que messages sea una lista no vacía y que cada mensaje tenga una estructura aceptada. No sustituyas el diagnóstico real por una lista genérica: el texto devuelto por el servidor debe indicar qué parte no pudo interpretar.
En conversaciones con razonamiento y herramientas también puede aparecer un 400 cuando el cliente no conserva correctamente reasoning_content. Ese caso requiere revisar la secuencia completa, no desactivar campos al azar. Registra el cuerpo ya depurado y compáralo con la referencia oficial de Chat Completions.
Error 401: autenticación fallida
El 401 indica que la autenticación ha fallado por una clave incorrecta. Confirma que la aplicación lee la variable adecuada, que no hay espacios ni saltos de línea y que la cabecera tiene la forma Authorization: Bearer CLAVE. Una clave creada para otro proveedor no sirve aunque el cliente use un formato compatible con OpenAI.
- No imprimas la clave completa en consola, analítica o informes.
- Si estuvo expuesta, revócala y crea otra en la plataforma oficial.
- Reinicia el proceso si las variables de entorno solo se cargan al arrancar.
- Prueba la misma clave con la llamada cURL mínima para separar un problema de credenciales de uno del SDK.
Error 402: saldo insuficiente
Un 402 no se resuelve cambiando el prompt. DeepSeek lo asocia a una cuenta sin saldo disponible. El endpoint oficial GET /user/balance devuelve is_available y un desglose por moneda con saldo total, concedido y recargado.
curl https://api.deepseek.com/user/balance \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}"Si is_available es false, revisa la facturación y recarga desde la cuenta correspondiente. Si esta comprobación devuelve 401, resuelve primero la autenticación. No publiques importes fijos en una guía de errores, porque el precio y el saldo dependen del modelo y de la cuenta.
Error 422: parámetros no válidos
El 422 significa que la solicitud contiene parámetros no válidos. Comprueba el nombre del modelo, los valores permitidos, los tipos de datos y las dependencias entre campos. Por ejemplo, un valor puede existir en otro proveedor pero no estar admitido por el endpoint elegido. Elimina temporalmente los parámetros opcionales y reincorpóralos uno por uno.
Los identificadores principales documentados son deepseek-v4-pro y deepseek-v4-flash. El registro oficial de cambios de DeepSeek V4 indica que deepseek-chat y deepseek-reasoner se retirarán el 24 de julio de 2026 a las 15:59 UTC. A fecha de verificación aún son alias de compatibilidad; no debe afirmarse que ya están retirados, pero tampoco conviene usarlos en código nuevo.
Error 429: límite de concurrencia
La página genérica describe el 429 como solicitudes enviadas demasiado rápido. La documentación actual de concurrencia precisa que el límite se calcula por cuenta, no por clave: una solicitud ocupa una conexión desde que se envía hasta que termina la respuesta. Superar la capacidad produce 429.
Los valores documentados en la fecha de verificación son 500 conexiones para deepseek-v4-pro y 2500 para deepseek-v4-flash. No abras más claves para intentar multiplicarlos. Limita el número de tareas en vuelo, libera conexiones terminadas y aplica una cola. DeepSeek permite solicitar ampliación de capacidad sin coste adicional, sujeta a las necesidades del negocio.
Errores 500 y 503: servidor y sobrecarga
El 500 corresponde a un problema interno del servidor; el 503, a sobrecarga por tráfico elevado. En ambos casos, conserva el trabajo local, espera y reintenta un número limitado de veces. Consulta el componente API en la página oficial de estado de DeepSeek. Una guía permanente no debe copiar el estado visible en un momento concreto.
Si el 500 persiste cuando la página de estado no muestra una incidencia, prepara una reproducción mínima y contacta con el soporte de la API. No atribuyas el fallo a una región, modelo o bloqueo sin evidencia del proveedor.
Manejo seguro en Node.js
Este ejemplo usa fetch, registra el estado y el cuerpo sin exponer la clave, y solo reintenta 429, 500 y 503. La espera exponencial con variación aleatoria es una decisión del cliente; DeepSeek no publica en estas páginas un intervalo obligatorio, un número máximo ni una garantía de cabecera Retry-After.
const apiKey = process.env.DEEPSEEK_API_KEY;
if (!apiKey) throw new Error("Falta DEEPSEEK_API_KEY");
const retryable = new Set([429, 500, 503]);
const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function createCompletion(maxAttempts = 4) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const response = await fetch(
"https://api.deepseek.com/chat/completions",
{
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "deepseek-v4-pro",
messages: [{ role: "user", content: "Responde solo: OK" }],
thinking: { type: "disabled" },
stream: false,
}),
}
);
const rawBody = await response.text();
if (response.ok) {
return JSON.parse(rawBody.trim());
}
console.error(`DeepSeek HTTP ${response.status}`, rawBody);
if (!retryable.has(response.status) || attempt === maxAttempts) {
throw new Error(`La solicitud falló con HTTP ${response.status}`);
}
const delayMs = 750 * 2 ** (attempt - 1)
+ Math.floor(Math.random() * 250);
await wait(delayMs);
}
}
const result = await createCompletion();
console.log(result.choices[0].message.content);No apliques reintentos ciegos a flujos que ejecuten pagos, escrituras o herramientas con efectos externos. El servidor tampoco documenta una clave de idempotencia en estas referencias. Diseña esos flujos para detectar duplicados antes de repetir una operación.
Lo que no es un código HTTP
- Líneas vacías: en una respuesta no transmitida pueden ser el mecanismo de mantenimiento de conexión. En streaming, el equivalente es el comentario SSE
: keep-alive. finish_reason="insufficient_system_resource": es un motivo de finalización dentro del objeto de respuesta y puede aparecer con HTTP 200; no es sinónimo automático de 500 o 503.finish_reason="length": indica que se alcanzó el límite de generación o de contexto, no un error de autenticación o facturación.
Lista de diagnóstico
- Anota el estado HTTP y conserva el cuerpo de respuesta ya depurado.
- Repite la llamada mínima con cURL y el mismo endpoint.
- Para 400 o 422, elimina parámetros opcionales y valida el esquema.
- Para 401, verifica cabecera, variable de entorno y clave activa.
- Para 402, consulta
/user/balance. - Para 429, mide solicitudes en vuelo a nivel de cuenta.
- Para 500 o 503, comprueba el estado oficial y reintenta con límite.
- Si persiste, comparte una reproducción sin secretos con soporte.
Limitaciones de esta guía
Los códigos describen categorías, no una causa única para cada integración. Un proxy, una biblioteca o una red corporativa puede transformar la respuesta. DeepSeek tampoco publica aquí un esquema universal para todos los cuerpos no exitosos. Por eso el diagnóstico debe conservar el estado y el cuerpo reales, junto con el endpoint, el modelo y una solicitud mínima reproducible.
Preguntas frecuentes
¿Debo reintentar todos los errores?
No. Corrige 400, 401, 402 y 422 antes de repetir. Reserva los reintentos limitados para 429, 500 y 503, y evita repetir operaciones con efectos externos sin control de duplicados.
¿Una clave nueva aumenta la concurrencia?
No. La concurrencia se agrega a nivel de cuenta independientemente de la clave utilizada.
¿Un 402 significa que la clave es incorrecta?
No. La documentación asigna 401 a autenticación y 402 a saldo insuficiente. Consulta el saldo con la misma clave para distinguirlos.
¿Puedo asumir que un 503 afecta a todos los usuarios?
No. Confirma el alcance en el estado oficial y evita generalizar a partir de una sola solicitud, región o red.
¿Las líneas vacías son una respuesta rota?
No necesariamente. DeepSeek las utiliza como mantenimiento de conexión en solicitudes no transmitidas. El analizador debe tolerar ese espacio en blanco y esperar el cuerpo JSON final.