DeepSeek Error Codes: como corrigir 400, 401, 402, 422, 429, 500 e 503

Data de revisão: 4 de maio de 2026

DeepSeek Error Codes são os códigos HTTP retornados pela DeepSeek API quando uma chamada falha por formato inválido, autenticação, saldo, parâmetros, limite de requisições ou instabilidade do servidor. O ponto mais importante é: nem todo erro deve ser resolvido com retry. Em muitos casos, repetir a mesma requisição só aumenta custo, latência e ruído nos logs.

Na prática, os erros 400, 401, 402 e 422 normalmente exigem corrigir o request, a autenticação, o saldo ou os parâmetros. Já os erros 429, 500 e 503 podem justificar retry controlado, backoff, redução de concorrência ou checagem da página de status. A documentação oficial da DeepSeek lista os códigos 400, 401, 402, 422, 429, 500 e 503 como os principais erros da API, com causas e soluções resumidas para cada um.

Este guia mostra como diagnosticar cada código, quando tentar novamente, quando parar, como montar uma chamada mínima correta e como registrar logs sem vazar secrets. Ele também considera a documentação atual da DeepSeek API, que hoje usa https://api.deepseek.com como base URL no formato OpenAI e lista deepseek-v4-flash e deepseek-v4-pro como modelos atuais.

---

Resumo rápido dos DeepSeek Error Codes

Código	Nome oficial	O que significa	Correção rápida	Fazer retry?
400	Invalid Format	O corpo da requisição está em formato inválido.	Corrija o JSON, headers, estrutura de messages ou formato do payload.	Não. Corrija antes.
401	Authentication Fails	A autenticação falhou por API key errada ou ausente.	Verifique Authorization: Bearer ${DEEPSEEK_API_KEY} e a key usada.	Não.
402	Insufficient Balance	A conta ficou sem saldo disponível.	Confira saldo e faça top-up.	Não.
422	Invalid Parameters	A requisição contém parâmetros inválidos.	Corrija modelo, tipos, valores, schema ou combinações inválidas.	Não.
429	Rate Limit Reached	As requisições estão rápidas ou concorrentes demais.	Reduza ritmo, use fila e backoff.	Sim, com backoff.
500	Server Error	Erro temporário no servidor da DeepSeek.	Retry limitado após breve espera; contate suporte se persistir.	Sim, limitado.
503	Server Overloaded	Servidor sobrecarregado por tráfego alto.	Aguarde, use backoff maior e fallback se necessário.	Sim, com cautela.

A tabela acima segue os nomes oficiais documentados pela DeepSeek para os códigos de erro da API.

---

Antes de corrigir: teste uma chamada mínima

Antes de investigar um erro 400 DeepSeek, erro 401 DeepSeek API ou erro 429 rate limit, elimine as variáveis. Faça uma chamada mínima, sem tool calls, sem JSON mode, sem múltiplos turnos e sem parâmetros extras.

Confira este checklist:

Item	O que verificar
base_url	Use https://api.deepseek.com no formato OpenAI.
Endpoint	Use /chat/completions.
API key	Envie Authorization: Bearer ${DEEPSEEK_API_KEY}.
Content-Type	Envie Content-Type: application/json.
Modelo	Use deepseek-v4-flash ou deepseek-v4-pro.
messages	Use um array com pelo menos uma mensagem válida.
stream	Teste primeiro com false; depois ative streaming.
Saldo	Verifique se a conta tem saldo disponível.
Status	Consulte a página de status para diferenciar API e Web Chat.

A documentação atual mostra deepseek-v4-flash e deepseek-v4-pro como valores de modelo aceitos, enquanto deepseek-chat e deepseek-reasoner aparecem como nomes antigos a serem descontinuados em 24 de julho de 2026. Para compatibilidade, esses nomes antigos correspondem aos modos non-thinking e thinking do deepseek-v4-flash.

Exemplo cURL mínimo

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "Responda em uma frase: a API está funcionando?"
      }
    ],
    "thinking": { "type": "disabled" },
    "stream": false
  }'

Exemplo Python com OpenAI SDK

import os
from openai import OpenAI

api_key = os.environ.get("DEEPSEEK_API_KEY")
if not api_key:
    raise RuntimeError("Defina a variável DEEPSEEK_API_KEY antes de executar.")

client = OpenAI(
    api_key=api_key,
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "user", "content": "Responda em uma frase: a API está funcionando?"}
    ],
    stream=False,
    extra_body={"thinking": {"type": "disabled"}},
)

print(response.choices[0].message.content)

A documentação da DeepSeek informa que a API é compatível com formatos OpenAI/Anthropic, permitindo usar SDKs compatíveis ao ajustar base_url, api_key e model.

Exemplo Node.js

import OpenAI from "openai";

const apiKey = process.env.DEEPSEEK_API_KEY;

if (!apiKey) {
  throw new Error("Defina a variável DEEPSEEK_API_KEY antes de executar.");
}

const client = new OpenAI({
  baseURL: "https://api.deepseek.com",
  apiKey,
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages: [
      {
        role: "user",
        content: "Responda em uma frase: a API está funcionando?",
      },
    ],
    thinking: { type: "disabled" },
    stream: false,
  });

  console.log(completion.choices[0].message.content);
}

main().catch(console.error);

---

Erro 400 — Invalid Format

O erro 400 DeepSeek significa que o formato do corpo da requisição está inválido. Na documentação oficial, o nome é Invalid Format, e a correção recomendada é modificar o request body conforme a mensagem de erro retornada pela API.

Sintomas comuns

Você pode ver 400 quando a DeepSeek API não consegue interpretar o payload. Isso costuma acontecer com JSON malformado, campos no lugar errado, messages em formato incorreto, headers ausentes ou SDKs/wrappers antigos que enviam uma estrutura incompatível.

Causas comuns

As causas mais frequentes são:

Causa	Exemplo
JSON malformado	Vírgula extra, aspas ausentes, chaves não fechadas.
Content-Type ausente	Enviar JSON sem Content-Type: application/json.
messages inválido	Usar objeto em vez de array.
role inválido	Enviar um papel que não é aceito no endpoint.
Payload de tool calls incompleto	Falta de tool_call_id ou ordem errada das mensagens.
Thinking mode com tool calls	Não reenviar reasoning_content quando ele é obrigatório.

O caso de thinking mode + tool calls merece atenção. A DeepSeek documenta que, quando o modelo faz tool calls em thinking mode, o reasoning_content deve ser passado de volta integralmente em requisições subsequentes; se isso não acontecer, a API retorna erro 400.

Payload errado

{
  "model": "deepseek-v4-flash",
  "messages": {
    "role": "user",
    "content": "Olá"
  }
}

O problema é que messages precisa ser um array, não um objeto.

Payload correto

{
  "model": "deepseek-v4-flash",
  "messages": [
    {
      "role": "user",
      "content": "Olá"
    }
  ],
  "thinking": {
    "type": "disabled"
  },
  "stream": false
}

Como corrigir

Comece removendo todos os parâmetros opcionais. Teste apenas model, messages, thinking e stream. Depois adicione tools, response_format, stream_options e outros recursos gradualmente. Se o erro aparecer após adicionar um bloco específico, o problema provavelmente está naquele trecho.

Não faça retry automático em 400. O mesmo payload tende a falhar novamente até que o formato seja corrigido.

---

Erro 401 — Authentication Fails

O erro 401 DeepSeek API significa falha de autenticação. O nome oficial é Authentication Fails, e a causa documentada é uma API key incorreta.

Causas comuns

Causa	Como diagnosticar
API key ausente	A variável DEEPSEEK_API_KEY não foi carregada.
Header errado	O header precisa seguir o formato Authorization: Bearer ....
Key de outro ambiente	Produção usando key de teste, ou o contrário.
Key removida ou rotacionada	A aplicação está usando uma credencial antiga.
Espaços invisíveis	Variável com quebra de linha ou espaço no início/fim.

Diagnóstico seguro

Nunca imprima a API key completa em logs. Em vez disso, registre apenas um fingerprint parcial:

import os
import hashlib

key = os.environ.get("DEEPSEEK_API_KEY", "")
if not key:
    raise RuntimeError("DEEPSEEK_API_KEY não definida.")

fingerprint = hashlib.sha256(key.encode()).hexdigest()[:10]
print(f"API key carregada. fingerprint={fingerprint}")

Também confira se o código usa exatamente a variável esperada. Um erro comum é definir DEEPSEEK_API_KEY, mas o app ler OPENAI_API_KEY por engano, ou vice-versa.

Não faça retry em 401. A correção é ajustar a credencial, o header ou o ambiente.

---

Erro 402 — Insufficient Balance

O erro 402 saldo insuficiente aparece quando a conta não tem saldo disponível para continuar usando a API. O nome oficial é Insufficient Balance, e a solução indicada pela DeepSeek é verificar o saldo e adicionar fundos.

A DeepSeek também documenta um endpoint /user/balance, que retorna se o saldo está disponível e detalha total_balance, granted_balance e topped_up_balance. O total_balance inclui o saldo concedido e o saldo recarregado.

Checklist de faturamento

Verificação	Por que importa
is_available	Indica se o saldo é suficiente para chamadas da API.
total_balance	Mostra o saldo total disponível.
granted_balance	Mostra créditos concedidos ainda não expirados.
topped_up_balance	Mostra saldo adicionado via recarga.
Uso por token	A cobrança depende de tokens de entrada e saída.

A documentação de preços informa que a cobrança é baseada no total de tokens de input e output, e que os custos são deduzidos do saldo recarregado ou concedido, com preferência pelo saldo concedido quando ambos existem.

Como reduzir desperdício

Em produção, evite loops de retry para 402. Eles não resolvem o problema e podem gerar logs confusos. Em vez disso:

• pare a fila de novas chamadas;
• alerte o time responsável;
• verifique consumo recente;
• reduza requisições duplicadas;
• revise prompts longos;
• configure monitoramento de saldo.

---

Erro 422 — Invalid Parameters

O erro 422 parâmetros inválidos ocorre quando o formato geral do request é aceitável, mas um ou mais parâmetros não são válidos. A DeepSeek chama esse erro de Invalid Parameters e orienta modificar os parâmetros conforme a mensagem de erro.

Diferença entre 400 e 422

Código	Interpretação prática
400	O corpo da requisição está em formato inválido.
422	O corpo é legível, mas contém parâmetros inválidos.

Exemplos típicos de 422 incluem modelo inválido, tipo incorreto em um campo, valor fora do esperado, schema de tool mal definido ou combinações de parâmetros incompatíveis.

A referência do endpoint /chat/completions lista messages como obrigatório, exige pelo menos uma mensagem e mostra deepseek-v4-flash e deepseek-v4-pro como valores possíveis para model.

Método “bisect parameters”

Para encontrar o parâmetro culpado:

1. Rode a chamada mínima.
2. Adicione apenas um parâmetro opcional.
3. Teste novamente.
4. Repita até o erro aparecer.
5. Remova ou corrija o último parâmetro adicionado.

Atenção ao thinking mode

Em thinking mode, a documentação informa que temperature, top_p, presence_penalty e frequency_penalty não são suportados. Segundo a própria DeepSeek, definir esses parâmetros não deve disparar erro, mas também não terá efeito. Isso é importante porque muitos times interpretam comportamento inesperado como bug ou “DeepSeek API não funciona”, quando na verdade o parâmetro foi ignorado.

---

Erro 429 — Rate Limit Reached

O erro 429 rate limit significa que você está enviando requisições rápido demais ou com concorrência acima do permitido. Na documentação oficial, o nome é Rate Limit Reached.

A DeepSeek informa que limita dinamicamente a concorrência de usuários com base na carga do servidor. Quando o limite de concorrência é atingido, a API retorna imediatamente HTTP 429. A documentação também explica que, depois que uma requisição é enviada, pode haver um período conectado antes da resposta; em non-streaming, linhas vazias podem ser retornadas, e em streaming podem aparecer comentários SSE : keep-alive.

Como resolver 429

A solução não é “retry infinito”. O ideal é controlar tráfego:

Ação	Resultado esperado
Reduzir concorrência	Menos chamadas simultâneas.
Usar fila	Evita rajadas de requests.
Exponential backoff	Espera progressiva antes de tentar novamente.
Jitter	Evita que todos os workers tentem ao mesmo tempo.
Limite de tentativas	Impede loop infinito.
Respeitar Retry-After	Usa orientação do servidor quando disponível.

Pseudocódigo de retry

se status_code for 429:
    se existir Retry-After:
        esperar Retry-After
    senão:
        esperar backoff_exponencial + jitter

    tentar novamente até max_attempts
senão se status_code for 400, 401, 402 ou 422:
    não tentar novamente

Em sistemas de produção, trate 429 como sinal de pressão. Se sua aplicação simplesmente dobrar o número de retries, ela pode piorar o congestionamento.

---

Erro 500 — Server Error

O erro 500 DeepSeek é um erro do lado do servidor. O nome oficial é Server Error, e a solução documentada é tentar novamente após uma breve espera e contatar a DeepSeek se o problema persistir.

Use retry limitado, com backoff. Registre o status code, latência, modelo e número da tentativa. Se houver muitos 500 em sequência, pare de insistir indefinidamente e acione um alerta.

Quando investigar, pergunte:

Pergunta	Por que importa
O erro acontece em todos os modelos?	Ajuda a isolar modelo, payload ou serviço.
O erro acontece com payload mínimo?	Se não acontecer, o problema pode estar nos parâmetros.
O erro aparece em todos os ambientes?	Pode ser problema de rede, proxy ou credencial.
Há incidente na página de status?	Ajuda a diferenciar falha local e falha do serviço.

---

Erro 503 — Server Overloaded

O erro 503 server overloaded indica sobrecarga por tráfego alto. A documentação oficial nomeia esse código como Server Overloaded e recomenda tentar novamente após breve espera.

A diferença prática entre 500 e 503 é que 500 aponta para erro do servidor de forma mais genérica, enquanto 503 sugere indisponibilidade ou sobrecarga temporária. Em produção, 503 pede mais paciência: backoff maior, fila mais conservadora e, se a aplicação for crítica, fallback temporário para outro provedor.

A própria página de status da DeepSeek separa API Service e Web Chat Service, o que ajuda a diferenciar problemas da API de problemas do chat web/app.

Boas práticas para 503

Prática	Motivo
Backoff maior	Evita pressionar um serviço já sobrecarregado.
Circuit breaker	Pausa chamadas quando a taxa de falha sobe.
Fallback	Mantém parte do produto funcionando.
Alertas	Notifica o time antes de impacto maior.
Status page	Confirma se há incidente externo.

---

Fluxo de decisão: devo corrigir ou tentar novamente?

Código	Ação principal	Retry?
400	Corrigir payload, JSON, headers ou sequência de mensagens.	Não.
401	Corrigir autenticação e API key.	Não.
402	Corrigir saldo, top-up e monitoramento financeiro.	Não.
422	Corrigir parâmetros, modelo, tipos e schemas.	Não.
429	Reduzir ritmo, limitar concorrência e usar backoff.	Sim.
500	Retry limitado e checagem de persistência.	Sim, limitado.
503	Backoff maior, status page, fallback e circuit breaker.	Sim, com cautela.

A regra geral é simples: não faça retry automático em 4xx, exceto quando você tem uma razão explícita e documentada para isso. Para os códigos documentados da DeepSeek API, os 4xx desta lista indicam problema de request, autenticação, saldo ou parâmetros. Já 429, 500 e 503 podem ser temporários.

---

Estratégia de retry segura para produção

Uma boa estratégia de retry para DeepSeek API error codes deve evitar três erros: tentar novamente códigos que não são retryable, criar loops infinitos e duplicar custo sem controle.

Use:

• max_attempts;
• timeout por request;
• exponential backoff;
• jitter aleatório;
• retry apenas em 429, 500, 503 e timeouts bem definidos;
• logs com retry_count;
• fallback quando o serviço estiver degradado;
• controle de idempotência interno para evitar duplicidade de operações downstream.

import os
import time
import random
from openai import OpenAI, APIStatusError, APITimeoutError, APIConnectionError

RETRYABLE_STATUS_CODES = {429, 500, 503}

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
    timeout=60,
)

def sleep_before_retry(attempt: int, retry_after: str | None = None) -> None:
    if retry_after:
        try:
            time.sleep(min(float(retry_after), 60))
            return
        except ValueError:
            pass

    base_delay = 1.5
    max_delay = 30
    delay = min(max_delay, base_delay * (2 ** (attempt - 1)))
    jitter = random.uniform(0, 1)
    time.sleep(delay + jitter)

def call_deepseek_with_retry(prompt: str, max_attempts: int = 4) -> str:
    for attempt in range(1, max_attempts + 1):
        try:
            response = client.chat.completions.create(
                model="deepseek-v4-flash",
                messages=[{"role": "user", "content": prompt}],
                stream=False,
                extra_body={"thinking": {"type": "disabled"}},
            )
            return response.choices[0].message.content

        except APIStatusError as exc:
            status_code = exc.status_code

            if status_code not in RETRYABLE_STATUS_CODES:
                raise

            if attempt == max_attempts:
                raise

            retry_after = None
            if exc.response is not None:
                retry_after = exc.response.headers.get("Retry-After")

            sleep_before_retry(attempt, retry_after)

        except (APITimeoutError, APIConnectionError):
            if attempt == max_attempts:
                raise
            sleep_before_retry(attempt)

    raise RuntimeError("Falha inesperada na chamada DeepSeek.")

Esse código evita retry em 400, 401, 402 e 422. Ele tenta novamente apenas quando o erro provavelmente é temporário.

---

Como registrar logs sem vazar secrets

Logs são essenciais para resolver códigos de erro DeepSeek, mas também podem vazar dados sensíveis. Nunca registre a API key, o header Authorization completo ou prompts confidenciais sem uma política explícita.

Registre:

Campo	Exemplo
status_code	429
model	deepseek-v4-flash
latency_ms	1840
retry_count	2
request_id	Se existir no header ou resposta.
stream	true ou false
error_type	rate_limit, server_error, invalid_parameters

Exemplo de log seguro:

{
  "event": "deepseek_api_error",
  "status_code": 429,
  "error_type": "rate_limit",
  "model": "deepseek-v4-flash",
  "latency_ms": 1840,
  "retry_count": 2,
  "stream": false,
  "request_id": "req_xxx_if_available",
  "authorization": "Bearer ***redacted***",
  "prompt_hash": "sha256:abc123..."
}

Se você precisa investigar conteúdo de prompt, use hash, amostragem controlada ou redaction. Em aplicações com dados pessoais, combine logs técnicos com políticas de privacidade e retenção.

---

Problemas parecidos que não são “error codes”

Nem todo problema da DeepSeek API aparece como um código HTTP claro. Alguns sintomas parecem erro, mas exigem outro diagnóstico.

Resposta lenta ou conexão aberta

A documentação de rate limit explica que uma requisição pode permanecer conectada enquanto aguarda resposta. Em non-streaming, podem aparecer linhas vazias; em streaming, comentários SSE : keep-alive. Se a inferência não começar após 10 minutos, o servidor fecha a conexão.

JSON mode “travado”

No endpoint /chat/completions, a documentação informa que response_format: { "type": "json_object" } habilita JSON Output, mas também alerta que você deve instruir o modelo a produzir JSON; caso contrário, ele pode gerar um fluxo longo de whitespace até atingir o limite de tokens.

finish_reason não é HTTP error code

finish_reason aparece dentro de uma resposta 200 e descreve por que a geração terminou. A documentação lista valores como stop, length, content_filter, tool_calls e insufficient_system_resource. Isso não deve ser confundido com HTTP 400, 401, 429, 500 ou 503.

“server is busy DeepSeek” no app/web

Mensagens como “server is busy DeepSeek” no app ou no chat web podem não corresponder exatamente aos DeepSeek API error codes. A página de status separa o serviço de API do serviço Web Chat, então sempre diferencie o problema do produto web/app e o problema do endpoint de API.

VPN, firewall e rede

Se a chamada mínima funciona em um ambiente, mas falha em outro, investigue proxy, firewall, DNS, bloqueios corporativos, timeout de gateway e inspeção TLS. Esses problemas podem gerar timeouts ou falhas de conexão sem retornar um código DeepSeek específico.

---

FAQ