Un mensaje como DeepSeek API error no identifica por sí solo la causa del problema. Para solucionarlo, necesitas distinguir entre una solicitud rechazada, un fallo de conexión y una respuesta que llegó, pero no contiene el resultado esperado.
Empieza por el código HTTP y el mensaje de error, no por cambiar de modelo al azar. Después, reproduce la llamada con una solicitud mínima. Así podrás decidir si debes corregir tu configuración, revisar la cuenta o esperar antes de volver a intentarlo.
Esta guía se centra en la API oficial y utiliza Chat Completions para los ejemplos. Si trabajas con un intermediario, una extensión o un agente, comprueba también qué proveedor recibe realmente la solicitud. El mensaje que muestra la aplicación puede no ser la respuesta original.
Identifica el error: tabla de diagnóstico rápido
La referencia general de errores de DeepSeek documenta estos siete códigos. La última columna resume cómo actuar antes de repetir la llamada.
| Código HTTP | Significado | Primera acción | ¿Reintentar sin corregir? |
|---|---|---|---|
400 | Formato inválido | Revisar el cuerpo de la solicitud. | No. |
401 | Autenticación fallida | Comprobar la API key. | No. |
402 | Saldo insuficiente | Revisar el saldo de la cuenta. | No. |
422 | Parámetros inválidos | Corregir campos, tipos o valores. | No. |
429 | Límite de solicitudes alcanzado | Reducir la carga y esperar. | Solo de forma limitada. |
500 | Error del servidor | Esperar y comprobar el servicio. | Sí, con límite. |
503 | Servidor sobrecargado | Esperar antes de repetir. | Sí, con límite. |
Si no recibiste un estado HTTP, comienza por la conexión y el tiempo de espera. Si recibiste 200, revisa también el contenido y la forma en que terminó la generación: el éxito del transporte no garantiza que tu aplicación haya obtenido una respuesta utilizable.
Como registro de diagnóstico, conserva el endpoint, el modelo, la hora con zona horaria, el código HTTP y una copia anonimizada del mensaje. Nunca publiques la API key, el encabezado Authorization ni datos privados incluidos en el prompt.
Prueba una solicitud mínima antes de modificar tu integración
Realiza la prueba desde el mismo servidor o entorno donde falla tu aplicación. Una llamada desde tu computadora puede funcionar aunque el servidor tenga otra configuración de red o credenciales diferentes.
La guía oficial de inicio utiliza https://api.deepseek.com como URL base para el formato compatible con OpenAI. Los identificadores recomendados actualmente son deepseek-flash y deepseek-v4-pro.
El siguiente ejemplo está preparado para Bash, disponible en Linux, macOS o WSL. Introduce una clave creada en la plataforma de DeepSeek. La entrada de la clave no se muestra en la terminal. La solicitud de generación puede consumir saldo.
read -r -s -p "API key de DeepSeek: " DEEPSEEK_API_KEY
printf '\n'
export DEEPSEEK_API_KEY
: > deepseek-diagnostico.json
curl --silent --show-error \
--connect-timeout 10 \
--max-time 60 \
--output deepseek-diagnostico.json \
--write-out '\nHTTP: %{http_code}\n' \
https://api.deepseek.com/chat/completions \
--header "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"model": "deepseek-flash",
"messages": [
{"role": "user", "content": "Confirma la conexión con una frase breve."}
],
"thinking": {"type": "disabled"},
"max_tokens": 128,
"stream": false
}'
curl_status=$?
printf 'Salida de curl: %s\n' "$curl_status"
cat deepseek-diagnostico.jsonEl archivo deepseek-diagnostico.json conserva el cuerpo recibido. El tiempo de 60 segundos es una elección para esta prueba, no un límite oficial de DeepSeek. Según el manual de cURL, el código de salida del programa y el estado HTTP son datos diferentes: sin una opción de fallo por HTTP, una respuesta 401 puede acompañarse de una salida de cURL igual a cero.
Si la prueba funciona: compara la solicitud real de tu aplicación con esta versión reducida. Añade el historial, las herramientas y los parámetros opcionales uno por uno. El objetivo es identificar qué cambio reproduce el fallo, no conservar permanentemente una configuración recortada.
Si también falla: sigue el diagnóstico correspondiente al código. Si hubo un corte de conexión, el archivo puede estar vacío o incompleto; no lo interpretes automáticamente como un JSON inválido generado por el modelo.
Cómo solucionar los errores de DeepSeek API por código
Error 400: revisa el JSON y la estructura enviada
Comprueba el cuerpo que sale de tu aplicación, no solo el objeto antes de convertirlo a JSON. Busca comillas sin escapar, campos truncados o un arreglo messages vacío. Reduce el contenido a un mensaje de texto y compara su estructura con la referencia de Chat Completions.
Evita mezclar protocolos: una solicitud de Chat Completions usa messages, mientras que la Responses API utiliza input. Cambiar únicamente la URL no convierte un cuerpo de solicitud de un formato al otro.
Caso especial: razonamiento y herramientas. La documentación de Thinking Mode exige devolver el reasoning_content de los turnos anteriores en solicitudes posteriores que incluyen tools, incluso si algún turno no ejecutó una herramienta. Omitirlo puede producir un 400. Sin tools, ese contenido no necesita reenviarse y se ignora si se incluye.
Cuando el fallo aparece después del primer turno, revisa cómo tu integración guarda y reconstruye los mensajes del asistente. No elimines reasoning_content de todo el historial como solución universal.
Error 401: comprueba la clave y el entorno de ejecución
Verifica que la clave corresponda a DeepSeek y que el proceso que realiza la llamada reciba el valor correcto. Utilizar una biblioteca compatible con OpenAI no convierte una clave de otro proveedor en una credencial válida para DeepSeek.
Revisa el encabezado Authorization: Bearer TU_API_KEY, los espacios o saltos de línea añadidos al copiar la clave y la variable de entorno del servidor. Presta especial atención a contenedores, tareas programadas y entornos de producción: pueden estar usando una configuración distinta a la de tu terminal.
Si cambiaste la variable de entorno, vuelve a iniciar el proceso que la lee y repite la prueba mínima. Si la clave quedó expuesta, revócala y reemplázala. No necesitas compartirla con nadie para demostrar que existe un error de autenticación.
Error 402: consulta el saldo de la cuenta utilizada
Comprueba el saldo de la cuenta asociada a la clave que falla. Tener una sesión abierta en la plataforma o disponer de fondos en otra cuenta no demuestra que esa credencial tenga saldo disponible.
DeepSeek ofrece Get User Balance para consultar esta información. Con la misma variable de entorno de la prueba anterior, ejecuta:
curl --silent --show-error \
--connect-timeout 10 --max-time 30 \
https://api.deepseek.com/user/balance \
--header "Authorization: Bearer ${DEEPSEEK_API_KEY}"En una respuesta correcta, is_available indica si el saldo es suficiente para realizar llamadas. balance_infos contiene la moneda y los importes, incluido total_balance. No confundas un 200 de esta consulta con una confirmación de que el saldo es suficiente: revisa esos campos.
Si acabas de recargar y el problema continúa, comprueba que el pago figure en la cuenta correcta y consulta nuevamente el saldo. No repitas la generación de forma indefinida esperando que el estado de facturación cambie.
Error 422: corrige los parámetros, no solo la sintaxis
Un documento puede ser JSON válido y contener valores que el endpoint no acepta. Revisa el nombre del parámetro señalado por el mensaje, su tipo y su rango permitido. Por ejemplo, compara un número enviado como texto con el tipo esperado por la referencia.
Durante el diagnóstico, elimina las opciones que no sean necesarias y reincorpóralas por separado. Revisa especialmente las combinaciones de modo de razonamiento, salida estructurada, herramientas y streaming.
No supongas que todos los parámetros de un proveedor funcionan igual en otro. La guía de Thinking Mode, por ejemplo, indica que temperature, presence_penalty y frequency_penalty se ignoran en ese modo sin provocar un error. Un parámetro sin efecto no equivale necesariamente a un 422.
Error 429: reduce la concurrencia y controla la cola
La documentación de límites publica 2,500 conexiones simultáneas para deepseek-flash y 500 para deepseek-v4-pro por cuenta. Cada solicitud cuenta desde su envío hasta completar la respuesta.
No son solicitudes por minuto. El límite se comparte entre las API keys de la cuenta. Revisa las condiciones vigentes antes de dimensionar producción.
Como medida de implementación, usa una cola y establece un máximo de trabajos activos. Si varias tareas empiezan al mismo tiempo, distribuye su inicio; si las respuestas se vuelven más lentas, reduce el número de llamadas en curso en lugar de seguir acumulándolas.
Añade reintentos con espera progresiva y un límite de intentos. Para necesidades sostenidas, consulta con el proveedor la capacidad autorizada.
Los endpoints de Search y Fetch tienen límites propios de solicitudes por segundo. No apliques automáticamente la tabla de concurrencia de los modelos a esos servicios.
Errores 500 y 503: comprueba el servicio antes de cambiar la cuenta
Abre la página oficial de estado y revisa el componente correspondiente. La página distingue los servicios de API, chat, búsqueda y extracción; que una parte funcione no permite concluir que todas estén disponibles.
Mientras investigas, conserva el trabajo pendiente, reduce la presión sobre el servicio y permite solo reintentos limitados. Si el problema se repite en solicitudes mínimas, registra sus horarios y escala el caso con esa evidencia.
No sustituyas una API key válida ni agregues saldo solo por recibir un error del servidor. Tampoco interpretes la ausencia de una incidencia publicada como prueba de que tu solicitud no pudo fallar: utiliza el estado público como una señal adicional, junto con tus registros.
Error 404 o “model not found”: revisa la ruta y el identificador
Un 404 o un mensaje de modelo no encontrado necesita contexto. Identifica quién lo devolvió: DeepSeek, un proxy o la plataforma desde la que llamas. No todos los proveedores utilizan los mismos nombres de modelo ni las mismas rutas.
Para la prueba de esta guía, el destino es POST https://api.deepseek.com/chat/completions. Si tu biblioteca construye la ruta automáticamente, revisa la URL final para detectar segmentos duplicados. No coloques la ruta completa de Chat Completions en un campo que espera únicamente la URL base.
Consulta Lists Models para obtener los identificadores disponibles y, cuando se proporcionen, sus capacidades:
curl --silent --show-error \
--connect-timeout 10 --max-time 30 \
https://api.deepseek.com/models \
--header "Authorization: Bearer ${DEEPSEEK_API_KEY}"Los tutoriales antiguos pueden contener deepseek-chat o deepseek-reasoner. DeepSeek anunció su retiro para el 24 de julio de 2026. No los uses como punto de partida para una integración nueva; comprueba el identificador vigente en lugar de adivinarlo.
Tampoco confundas la ruta con el contenido solicitado. En Fetch, un 404 puede indicar que no se obtuvo contenido utilizable de la página de destino; no significa necesariamente que hayas escrito mal la URL de la API. El significado depende del endpoint.
Timeouts y errores de conexión: separa la red del servidor
Un timeout indica que se agotó una espera del cliente; no demuestra por sí solo que DeepSeek haya devuelto un error HTTP. Antes de aumentar el plazo, comprueba dónde se corta la operación: resolución de dominio, conexión, negociación TLS, espera de respuesta o lectura del contenido.
Compara una solicitud desde el mismo entorno de ejecución, revisa el proxy y el firewall, y verifica la configuración de certificados. No desactives la validación TLS ni envíes la clave a un proxy desconocido para intentar resolver el problema.
Si intervienen varios componentes, revisa sus plazos por separado. Aumentar el timeout de Python no elimina un límite más corto en tu servidor web, balanceador o plataforma de automatización. Establece también un plazo total para el trabajo, no únicamente esperas de red.
El mantenimiento de conexión puede incluir líneas vacías sin streaming o comentarios SSE : keep-alive. DeepSeek cierra la conexión si la inferencia no empieza en diez minutos; tu aplicación puede establecer un plazo menor.
En streaming, no intentes interpretar cada línea como JSON: puede ser un comentario de mantenimiento. El formato de Chat Completions utiliza eventos SSE y termina normalmente con data: [DONE]. Si la conexión se interrumpe antes de completarse, marca la respuesta como parcial.
HTTP 200 con respuesta vacía, JSON inválido o texto incompleto
Si la solicitud terminó correctamente a nivel HTTP, inspecciona choices, el contenido y finish_reason antes de guardar el resultado como definitivo. La referencia de respuesta distingue, entre otros, estos motivos:
| Valor | Cómo interpretarlo |
|---|---|
length | Se alcanzó un límite de generación; revisa también el espacio de contexto. |
tool_calls | El modelo solicitó herramientas; no es necesariamente un fallo. |
insufficient_system_resource | La inferencia se interrumpió por falta de recursos. |
aborted | La generación fue interrumpida. |
Estos valores no son códigos HTTP. Por ejemplo, insufficient_system_resource no debe registrarse automáticamente como un 503 si la respuesta HTTP recibida fue 200. Conserva ambos datos por separado.
En JSON Output, revisa también el contenido en blanco. La guía oficial indica que debes usar response_format: {"type": "json_object"}, pedir JSON en el prompt y ofrecer un ejemplo del formato esperado. Si la salida no se reconoce como JSON, la API puede reemplazarla por espacios, incluso con finish_reason="stop".
Antes de ejecutar json.loads(), comprueba si content.strip() está vacío. Si hay texto, captura los errores de análisis y valida los campos que tu aplicación necesita. Un JSON sintácticamente válido todavía puede tener valores o una estructura que no cumplen tus requisitos.
Si el contenido quedó truncado, ajusta el tamaño de la entrada o el presupuesto de salida dentro de los límites del modelo. Para contenidos vacíos, prueba un prompt más explícito y permite, como máximo, un número acotado de nuevos intentos. No guardes espacios como si fueran una respuesta correcta.
Ejemplo en Python: identifica el error sin reintentos ocultos
Instala el SDK en el entorno de tu proyecto y configura DEEPSEEK_API_KEY como variable de entorno. El ejemplo usa una clave de DeepSeek y envía la solicitud a su URL base, aunque la biblioteca se llame openai.
python -m pip install --upgrade openaiEl SDK de Python distingue errores HTTP y de conexión. Aquí se desactivan los reintentos para observar una sola llamada. El timeout no garantiza una duración total.
import os
import openai
def main() -> int:
api_key = os.environ.get("DEEPSEEK_API_KEY", "").strip()
if not api_key:
print("Falta la variable de entorno DEEPSEEK_API_KEY.")
return 1
actions = {
400: "Revisa el cuerpo de la solicitud.",
401: "Revisa la clave y el entorno del proceso.",
402: "Consulta el saldo de esta cuenta.",
422: "Revisa los parámetros indicados por el servidor.",
429: "Reduce la carga antes de reintentar.",
500: "Comprueba el servicio y espera antes de reintentar.",
503: "Comprueba el servicio y espera antes de reintentar.",
}
with openai.OpenAI(
api_key=api_key,
base_url="https://api.deepseek.com",
timeout=60.0,
max_retries=0,
) as client:
try:
response = client.chat.completions.create(
model="deepseek-flash",
messages=[{
"role": "user",
"content": "Confirma la conexión con una frase breve.",
}],
max_tokens=128,
stream=False,
extra_body={"thinking": {"type": "disabled"}},
)
except openai.APITimeoutError:
print("Se agotó una espera del cliente; revisa red y plazos.")
return 1
except openai.APIConnectionError:
print("Falló la conexión; revisa DNS, TLS, proxy y firewall.")
return 1
except openai.APIStatusError as error:
print(f"HTTP {error.status_code}")
print(actions.get(error.status_code, "Revisa endpoint y mensaje."))
# Inspecciona error.body localmente si necesitas más detalle.
# No publiques credenciales, prompts privados ni datos personales.
return 1
if not response.choices:
print("La respuesta no contiene choices; revisa el cuerpo recibido.")
return 1
choice = response.choices[0]
text = (choice.message.content or "").strip()
print(f"finish_reason: {choice.finish_reason}")
if choice.finish_reason != "stop" or not text:
print("La prueba no terminó con una respuesta de texto completa.")
return 1
print(text)
return 0
if __name__ == "__main__":
raise SystemExit(main())La comprobación final es deliberadamente estricta para esta prueba de texto sin herramientas. No la traslades sin cambios a un agente: allí, recibir tool_calls puede ser un paso normal del flujo, no un fallo.
APITimeoutError deriva de APIConnectionError, por eso se captura primero. Para errores HTTP, APIStatusError proporciona el estado y la respuesta. Inspecciona el cuerpo en privado antes de compartirlo.
Reintentos controlados: evita duplicar la carga y el trabajo
La documentación del SDK indica que, de manera predeterminada, realiza dos reintentos con espera exponencial para ciertos fallos de conexión y estados como 429 y 5xx. max_retries=0 los desactiva; max_retries=2 permite hasta dos reintentos adicionales a la llamada inicial.
Elige un solo responsable de los reintentos. Si tu aplicación tiene una política propia, desactiva la del SDK. De lo contrario, una cola que repite cada trabajo puede multiplicar las llamadas que la biblioteca ya está repitiendo.
Para una política propia, establece un máximo de intentos, un plazo total y esperas progresivas con una pequeña variación aleatoria. Esta variación, conocida como jitter, evita que todos tus trabajadores vuelvan a llamar al mismo tiempo. Si recibes el encabezado Retry-After, respeta la espera indicada; si supera el plazo de tu trabajo, detén o pospón la tarea.
No reinicies automáticamente una operación con efectos externos solo porque terminó la conexión. Un timeout no confirma que el servidor no haya procesado la solicitud. En agentes que envían correos, registran pedidos o modifican datos, utiliza identificadores internos de operación para impedir duplicados.
Tampoco vuelvas a ejecutar un flujo completo si ya entregaste parte de una respuesta en streaming. Decide de forma explícita si vas a descartar la salida parcial, solicitar una continuación o informar al usuario de la interrupción.
Qué enviar a soporte si el error continúa
Prepara una reproducción pequeña y anonimizada. Incluye la hora con zona horaria, el endpoint, el modelo, el código HTTP, el mensaje recibido, la versión de tu biblioteca y si usabas streaming o herramientas. Añade un identificador de solicitud solo si la respuesta lo proporciona.
Indica también si la misma petición falla fuera de tu integración, cuántos intentos realizaste y qué cambios probaste. Esto permite separar problemas de cuenta, formato y transporte sin enviar conversaciones completas.
La documentación oficial publica el contacto [email protected]. No adjuntes claves, encabezados de autenticación, datos personales ni capturas que los revelen.
Preguntas frecuentes
¿Por qué aparece openai.AuthenticationError si estoy usando DeepSeek?
La excepción pertenece a la biblioteca, no identifica por sí sola al proveedor. Si la URL base apunta a DeepSeek, revisa las credenciales de DeepSeek; no necesitas crear una clave de OpenAI.
¿Crear otra API key resuelve el error 429?
No: las claves de una misma cuenta comparten el límite. Reduce las solicitudes simultáneas y controla la cola de trabajo.
¿Debo borrar la caché del navegador para arreglar un error de API?
No es el primer paso para una llamada que sale de tu servidor. Empieza por la solicitud HTTP y su respuesta. Borrar datos del navegador puede ayudar con ciertos problemas de una interfaz, pero no sustituye revisar credenciales, parámetros o saldo del proceso que llama a la API.
¿Cómo sé si falla mi integración o la API?
Repite una solicitud mínima desde el mismo entorno y con la misma cuenta. Si funciona, compara el cuerpo, el historial y las opciones que añade tu integración. Si también falla, conserva la respuesta exacta y sigue la ruta de diagnóstico correspondiente, sin asumir automáticamente una caída general.
La regla práctica: identifica quién respondió, conserva el código y reduce la solicitud. Corrige la configuración antes de insistir y reserva los reintentos para situaciones en las que esperar pueda cambiar el resultado.
Última verificación documental: 10 de noviembre de 2026. Los ejemplos se basan en la documentación enlazada; no se realizaron llamadas autenticadas a una cuenta de DeepSeek para esta guía.