Os DeepSeek Error Codes indicam se uma chamada falhou por formato, autenticação, saldo, parâmetros, excesso de concorrência ou uma condição temporária do servidor. A decisão mais importante é saber quando corrigir a requisição e quando tentar novamente: repetir um payload inválido não resolve o problema e pode esconder a causa real.
Última verificação editorial: 19 de julho de 2026. Este guia foi conferido com a documentação oficial da API e usa apenas os IDs explícitos deepseek-v4-flash e deepseek-v4-pro.
Aviso de independência: DeepSeek Português é um site independente, sem afiliação com a DeepSeek. Este conteúdo explica a API oficial, mas não substitui a documentação, o suporte ou os termos da empresa.
Tabela rápida: causa, correção e retry
| Código | Nome documentado | Ação principal | Retry? |
|---|---|---|---|
400 | Invalid Format | Corrigir o formato do corpo, JSON ou sequência de mensagens | Não, até corrigir |
401 | Authentication Fails | Validar API key e header de autorização | Não |
402 | Insufficient Balance | Verificar saldo e recarregar a conta | Não |
422 | Invalid Parameters | Corrigir modelo, tipos, valores ou parâmetros incompatíveis | Não, até corrigir |
429 | Rate Limit Reached | Reduzir concorrência, enfileirar e aplicar backoff | Sim, limitado |
500 | Server Error | Aguardar brevemente e repetir com limite | Sim, limitado |
503 | Server Overloaded | Aguardar, reduzir pressão e repetir com cautela | Sim, limitado |
Os nomes e as causas acima seguem a página oficial de Error Codes. A API pode devolver uma mensagem mais específica no corpo da resposta; registre-a de forma segura e use essa mensagem para localizar o campo problemático.
Primeiro passo: reduza para uma chamada mínima
Antes de alterar retries, proxy ou infraestrutura, remova recursos opcionais. Teste uma chamada sem tools, JSON Output, histórico longo ou streaming. Isso separa falhas básicas de autenticação e endpoint de erros introduzidos por um recurso adicional.
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 somente: OK"}
],
"thinking": {"type": "disabled"},
"stream": false
}'- Use a base URL
https://api.deepseek.come o endpoint/chat/completions. - Envie a chave somente no backend, no formato
Authorization: Bearer .... - Comece com
stream: falsepara inspecionar uma resposta JSON completa. - Se a chamada mínima funcionar, reintroduza um recurso por vez até reproduzir a falha.
Erro 400: Invalid Format
O HTTP 400 indica que o corpo não está no formato esperado. As causas práticas incluem JSON malformado, messages enviado como objeto em vez de array, conteúdo no nível errado ou uma sequência incompleta de mensagens de ferramenta. Leia a mensagem devolvida pela API antes de editar o código.
Thinking Mode com Tool Calls
Há uma regra específica: quando o assistente realiza uma tool call em Thinking Mode, o reasoning_content daquela mensagem deve ser preservado e reenviado integralmente nas rodadas subsequentes. A documentação informa que omiti-lo nesse fluxo produz erro 400. Se não houve tool call entre duas mensagens do usuário, o raciocínio anterior não precisa ser reenviado.
Veja a implementação completa no guia do DeepSeek Thinking Mode. Não tente corrigir um 400 apenas aumentando o timeout ou repetindo o mesmo corpo.
Erro 401: Authentication Fails
O HTTP 401 significa que a autenticação falhou. Confirme se a variável existe no processo que realmente executa a aplicação, se não contém espaços ou quebras de linha e se o código não está lendo OPENAI_API_KEY quando você definiu DEEPSEEK_API_KEY. Uma chave rotacionada também exige atualizar o segredo em cada ambiente.
- Não coloque a chave no JavaScript enviado ao navegador.
- Não imprima o header
Authorizationou a chave completa nos logs. - Se uma chave foi exposta em repositório, print ou mensagem, revogue-a e crie outra.
- Não faça retry automático: a mesma credencial continuará inválida.
Erro 402: Insufficient Balance
O HTTP 402 não é rate limit. Ele indica que a conta ficou sem saldo utilizável. Interrompa novas chamadas, confira o saldo na plataforma oficial e faça recarga quando necessário. A API também documenta GET /user/balance, que retorna is_available e os componentes do saldo.
Retries não adicionam saldo. Para produção, monitore consumo, alerte antes da interrupção e mantenha a página de preços da DeepSeek API separada da gratuidade ou dos limites dos produtos de chat.
Erro 422: Invalid Parameters
O HTTP 422 aparece quando o corpo é legível, mas contém parâmetros inválidos. Exemplos: nome de modelo não aceito, tipo incorreto, valor fora do formato permitido ou schema de ferramenta inválido. Comece com a chamada mínima e adicione cada parâmetro separadamente.
Em Thinking Mode, temperature, top_p, presence_penalty e frequency_penalty não têm efeito. A documentação diz que esses campos podem ser aceitos por compatibilidade sem gerar erro; portanto, comportamento inalterado após ajustar esses valores não é, por si só, um 422.
Erro 429: Rate Limit Reached
O HTTP 429 indica que as requisições estão rápidas demais ou que a conta excedeu a concorrência disponível. Em 19 de julho de 2026, a documentação informa os seguintes limites por conta:
| Modelo | Concorrência por conta |
|---|---|
deepseek-v4-flash | 2.500 conexões |
deepseek-v4-pro | 500 conexões |
Uma requisição ocupa uma conexão concorrente do envio até a conclusão da resposta. O cálculo é feito no nível da conta, independentemente da quantidade de API keys. A DeepSeek também oferece um pedido de expansão de capacidade e informa que essa expansão não tem custo adicional, mas a capacidade concedida depende da necessidade apresentada.
- Limite a quantidade de chamadas simultâneas no seu próprio backend.
- Use uma fila para absorver rajadas.
- Aplique exponential backoff com jitter e número máximo de tentativas.
- Se a resposta trouxer
Retry-After, respeite-o; não presuma que esse header sempre estará presente. - Não transforme cada 429 em várias novas requisições concorrentes.
Erros 500 e 503
O HTTP 500 é documentado como Server Error; o HTTP 503, como Server Overloaded. Os dois podem ser transitórios. Faça poucas tentativas, com espera crescente, e encerre o ciclo quando o limite for atingido. Se a operação do seu produto tiver efeitos externos, use uma chave de idempotência interna ou outro controle para não repetir ações downstream.
Não existe base pública para prometer um SLA, um tempo fixo de recuperação ou sucesso na próxima tentativa. Sua aplicação deve apresentar uma mensagem honesta, preservar a fila quando apropriado e permitir nova tentativa manual sem duplicar operações.
Timeout, conexão e keep-alive não são sempre HTTP
Uma falha de DNS, TLS, proxy, firewall ou conexão pode ocorrer antes de existir uma resposta HTTP. Já uma requisição aceita pode permanecer conectada enquanto aguarda capacidade. A DeepSeek documenta linhas vazias em chamadas non-streaming e comentários SSE : keep-alive em streaming. Se a inferência não começar após dez minutos, o servidor fecha a conexão.
Defina um timeout adequado ao seu produto, mas trate-o como limite do cliente, não como prova de que o servidor não processou nada. Não presuma custo zero após um timeout. Registre o horário, modelo, tentativa e identificadores disponíveis para reconciliar o evento.
Node.js: retry controlado e tratamento do SDK
O SDK OpenAI para Node.js lança subclasses de APIError para respostas 4xx/5xx e APIConnectionError para falhas de conexão. Ele também realiza retries automáticos por padrão. O exemplo desativa essa camada para que exista apenas uma política de retry, visível no código.
import OpenAI from "openai";
const apiKey = process.env.DEEPSEEK_API_KEY;
if (!apiKey) {
throw new Error("DEEPSEEK_API_KEY não definida");
}
const client = new OpenAI({
apiKey,
baseURL: "https://api.deepseek.com",
maxRetries: 0,
timeout: 60_000, // exemplo local: ajuste ao seu produto
});
const RETRYABLE = new Set([429, 500, 503]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function askDeepSeek(prompt, maxAttempts = 4) {
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
try {
const response = await client.chat.completions.create({
model: "deepseek-v4-flash",
messages: [{ role: "user", content: prompt }],
thinking: { type: "disabled" },
stream: false,
});
return response.choices[0].message.content;
} catch (error) {
const apiError = error instanceof OpenAI.APIError;
const connectionError = error instanceof OpenAI.APIConnectionError;
const status = apiError ? error.status : undefined;
const mayRetry = connectionError || RETRYABLE.has(status);
if (!mayRetry || attempt === maxAttempts) throw error;
const retryAfterHeader =
apiError && typeof error.headers?.get === "function"
? error.headers.get("retry-after")
: null;
const retryAfterValue = retryAfterHeader?.trim()
? Number(retryAfterHeader)
: Number.NaN;
const exponentialMs = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
const jitterMs = Math.floor(Math.random() * 500);
const waitMs = Number.isFinite(retryAfterValue)
? Math.min(60_000, retryAfterValue * 1_000)
: exponentialMs + jitterMs;
await sleep(waitMs);
}
}
}
console.log(await askDeepSeek("Responda somente: OK"));Em operações reais, acrescente fila, circuit breaker, métricas e cancelamento do cliente. Não registre o prompt completo por padrão. Se optar pelos retries internos do SDK, remova o loop manual ou ajuste maxRetries conscientemente para evitar tentativas multiplicadas.
Python: diferencie status, timeout e conexão
import os
from openai import OpenAI, APIStatusError, APITimeoutError, APIConnectionError
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com",
max_retries=0,
timeout=60.0, # exemplo local
)
try:
response = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[{"role": "user", "content": "Responda somente: OK"}],
stream=False,
extra_body={"thinking": {"type": "disabled"}},
)
print(response.choices[0].message.content)
except APIStatusError as exc:
print("status=", exc.status_code, "request_id=", exc.request_id)
raise
except APITimeoutError:
print("timeout do cliente")
raise
except APIConnectionError:
print("falha de conexão antes de uma resposta HTTP utilizável")
raiseEsse bloco apenas classifica a falha. Se você implementar retries em Python, aplique a mesma regra: 429, 500, 503 e falhas transitórias de conexão podem receber tentativas limitadas; 400, 401, 402 e 422 precisam de correção.
Quando o problema parece erro, mas a resposta foi 200
- JSON com whitespace: ao usar
response_format: {"type":"json_object"}, instrua explicitamente o modelo a devolver JSON e descreva o formato. Sem isso, a documentação alerta para uma sequência longa de whitespace. - Saída cortada: verifique
finish_reasone o limite de saída configurado; isso não é um HTTP 500. - Parâmetro sem efeito: temperature e penalidades são ignoradas em Thinking Mode.
- Streaming aparentemente parado: seu parser deve ignorar comentários SSE de keep-alive sem tratá-los como tokens ou JSON final.
Para respostas estruturadas, use o guia de JSON Output. Para contagem e reconciliação de custo, consulte DeepSeek Token Usage.
Aviso permanente sobre aliases legados
Em 24 de abril de 2026, a DeepSeek anunciou que deepseek-chat e deepseek-reasoner ficariam inacessíveis depois de 24 de julho de 2026, às 15:59 UTC. Durante a janela de compatibilidade, eles roteavam para o V4 Flash em Non-Thinking e Thinking, respectivamente. Independentemente da data em que você leia este guia, não use esses aliases em código novo: escolha deepseek-v4-flash ou deepseek-v4-pro e defina o modo explicitamente.
Logs seguros para diagnosticar falhas
- Registre status HTTP, tipo de erro, modelo, latência e número da tentativa.
- Registre um request ID somente quando ele realmente existir.
- Redija
Authorization, cookies, prompts, arquivos e dados pessoais. - Não inclua a API key em screenshots ou tickets.
- Defina retenção e acesso para logs; diagnóstico não justifica guardar tudo indefinidamente.
Leia também as páginas de segurança e privacidade deste site. Elas não descrevem automaticamente as práticas de qualquer aplicação de terceiros criada com a API.
Checklist antes de abrir um chamado
- Reproduza com uma chamada mínima e
stream: false. - Anote o código HTTP e a mensagem, sem copiar credenciais.
- Confirme base URL, endpoint, modelo explícito e ambiente da chave.
- Verifique saldo para 402 e concorrência para 429.
- Remova parâmetros opcionais e reintroduza um por vez.
- Confirme se o SDK já está fazendo retries.
- Teste DNS, proxy e firewall somente quando não houver resposta HTTP.
- Preserve horário, latência e request ID disponível para correlação.
Perguntas frequentes
Quais são os códigos oficiais da DeepSeek API?
A documentação lista 400, 401, 402, 422, 429, 500 e 503, com as descrições Invalid Format, Authentication Fails, Insufficient Balance, Invalid Parameters, Rate Limit Reached, Server Error e Server Overloaded.
Devo repetir uma requisição que retornou 400?
Não sem alterar o payload. Corrija o formato indicado pela mensagem de erro. Um retry idêntico tende a falhar novamente.
Qual é a diferença entre 402 e 429?
402 significa saldo insuficiente. 429 significa envio rápido demais ou concorrência excedida. O primeiro exige corrigir o saldo; o segundo exige controlar o tráfego.
Quantas vezes devo tentar novamente?
A DeepSeek não publica um número universal para cada aplicação. Defina um limite pequeno conforme latência, criticidade e risco de duplicidade, use backoff com jitter e permita uma recuperação controlada.
Erro no SDK é sempre erro da DeepSeek?
Não. O SDK pode lançar erro por timeout, DNS, TLS, proxy ou conexão sem receber um status da API. Diferencie APIError de APIConnectionError e registre a camada que falhou.