DeepSeek Error Codes: como corrigir erros da API

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.

Teste controlado: messages vazio retornou HTTP 400

Enviamos uma requisição autenticada com messages: [], sem dados pessoais, somente para observar a validação do payload.

Campo	Resultado
HTTP	400
Latência	312 ms
message	Empty input messages
type	invalid_request_error
code	invalid_request_error
param	null

Neste payload, o servidor respondeu 400, não 422. Leia também error.message, error.type e error.code, sem registrar chave ou conteúdo sensível. Não repita automaticamente um erro determinístico; corrija o corpo.

Não provocamos 401, 402, 429, 500 ou 503. Uma entrada inválida não prova que todo payload inválido receberá 400; outros campos podem ser classificados de forma diferente.

Veja o corpo correto em DeepSeek API, validação de argumentos em Tool Calls e a referência oficial.

Última verificação editorial: 24 de agosto de 2026. Este guia foi conferido com a documentação oficial da API. Os IDs hospedados documentados são deepseek-v4-flash, deepseek-v4-pro e deepseek-v4-flash-vision-exp. Somente o modelo Vision aceita imagens; Flash e Pro continuam aceitando entrada textual.

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 corpo, estrutura de mensagens, imagens ou sequência de ferramentas	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 primeiro uma chamada somente com texto, sem tools, JSON Output, histórico longo, streaming, imagens ou referência da Files API. Isso separa falhas básicas de autenticação e endpoint de erros introduzidos por um recurso adicional. Se a chamada textual funcionar e o erro aparecer apenas ao adicionar uma imagem, use o checklist específico de Vision abaixo.

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.com e o endpoint /chat/completions.
• Envie a chave somente no backend, no formato Authorization: Bearer ....
• Comece com stream: false para 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 para o Thinking Mode. Se a requisição incluir tools, o reasoning_content de toda mensagem assistant deve ser preservado e reenviado integralmente em todas as interações subsequentes, mesmo quando o modelo não realizar uma Tool Call naquela rodada. Omiti-lo pode produzir HTTP 400. Somente quando a requisição não incluir tools o raciocínio anterior pode ser omitido; se for enviado nesse caso, será ignorado.

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.

HTTP 400 com imagens e Vision

Na interface Chat Completions, somente deepseek-v4-flash-vision-exp aceita imagens. A documentação oficial informa que enviar uma imagem a deepseek-v4-flash ou deepseek-v4-pro retorna HTTP 400. Imagens também são aceitas apenas em mensagens com role: "user" nessa interface; colocá-las em mensagens system ou assistant produz o mesmo código.

Confira estes pontos antes de repetir a chamada:

• Use deepseek-v4-flash-vision-exp.
• Envie content como um array de blocos, com texto e image_url ou file.
• Confirme que o conteúdo real do arquivo é JPEG, PNG, GIF ou WebP — a detecção não depende apenas da extensão ou do MIME declarado.
• Não inclua manualmente no texto o token reservado de placeholder de imagem.
• Em URL externa, use um endereço HTTP(S) acessível, com no máximo 8.192 caracteres, e permita que o download termine em até 60 segundos.
• Respeite 48 MiB para o corpo da requisição e 32 MiB por imagem enviada inline ou por URL.
• Para uma imagem referenciada por file_id, respeite o limite de 64 MiB.
• Respeite o máximo de 600 imagens por requisição e os demais limites de tamanho e dimensão publicados no guia oficial.

Na Responses API, o formato é diferente: imagens usam blocos input_image e podem aparecer em mensagens user ou developer, além de resultados de ferramentas compatíveis. Não copie diretamente o formato de Chat Completions para Responses API.

Quando o problema está no file_id

A Files API atual armazena imagens para uso posterior com o modelo Vision. Confirme se o arquivo foi enviado com purpose="user_data", se pertence à mesma API key usada na inferência e se ainda aparece em GET /files ou GET /files/{file_id}. Um arquivo expirado ou excluído não deve continuar sendo referenciado.

O prazo opcional de expiração pode variar de uma hora a 30 dias. Quando os campos expires_after são omitidos, o arquivo é mantido permanentemente até ser excluído. A documentação não atribui um código HTTP exclusivo a toda possível falha de imagem ou arquivo; leia error.message, corrija a causa indicada e não faça retry cego.

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 Authorization ou 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 24 de agosto 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
deepseek-v4-flash-vision-exp	2.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. Para contas comuns, valores diferentes de user_id continuam compartilhando o limite total da conta. 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")
    raise

Esse 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_reason e 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

O prazo de retirada anunciado já passou. Em 29/07/2026, chamadas autenticadas aos dois aliases ainda retornaram HTTP 200 e V4 Flash nesta conta; porém, GET /models listou apenas os IDs V4 disponíveis naquele teste. Esse registro é histórico e anterior ao catálogo atual, que também inclui deepseek-v4-flash-vision-exp. Não presuma erro nem suporte permanente para aliases: use IDs explícitos e confira a lista oficial de modelos antes de publicar código novo.

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

1. Reproduza com uma chamada textual mínima e stream: false.
2. Anote o código HTTP e a mensagem, sem copiar credenciais ou conteúdo sensível.
3. Confirme base URL, endpoint, modelo explícito e ambiente da chave.
4. Se houver imagem, confirme modelo Vision, role, formato do bloco, tipo real do arquivo e limites de tamanho.
5. Se houver file_id, confirme que o arquivo existe, pertence à API key usada e não expirou nem foi excluído.
6. Verifique saldo para 402 e concorrência para 429.
7. Remova parâmetros opcionais e reintroduza um por vez.
8. Confirme se o SDK já está fazendo retries.
9. Teste DNS, proxy e firewall somente quando não houver resposta HTTP.
10. 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.

Por que uma imagem retorna HTTP 400?

Confirme que o modelo é deepseek-v4-flash-vision-exp. Em Chat Completions, a imagem deve estar em uma mensagem user e em um bloco image_url ou file; Flash e Pro não aceitam imagens. Verifique também o formato real do arquivo, o tamanho, a acessibilidade da URL e a validade do file_id. Corrija a causa indicada em error.message antes de tentar 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.

Fontes oficiais consultadas

• DeepSeek API — Models & Pricing
• DeepSeek API — Vision
• DeepSeek API — Files API
• DeepSeek API — Error Codes
• DeepSeek API — Rate Limit & Isolation
• DeepSeek API — Get User Balance
• DeepSeek API — Thinking Mode
• DeepSeek API — JSON Output
• DeepSeek V4 Preview Release — aviso dos aliases
• OpenAI Node SDK — erros, retries e timeouts
• OpenAI Python SDK — erros, retries e timeouts