Os erros do DeepSeek API se dividem em quatro categorias: autenticação, caminho e nome de modelo, limitação de taxa e timeout. A ordem correta de diagnóstico é: primeiro o código HTTP e o tipo de erro, depois o request ID e a reprodução mínima, e só então alterar o prompt ou trocar de modelo. Invertendo a ordem, é fácil confundir problema de configuração com limitação do modelo.

Este artigo separa as quatro categorias — 401, 404, 429 e timeout — e apresenta causas, passos de diagnóstico e código de backoff reutilizável. Modelos e preços seguem a página de preços do site.

Nota: DeepSeek é marca registrada de seu titular. Tipos de erro, critérios de limitação e comportamento da interface podem mudar entre versões; este artigo usa a situação comum de outubro de 2026 como exemplo e tem como referência final a documentação oficial.

1. Separe primeiro as quatro categorias

Status ou sintoma Significado comum Causa típica Ordem de tratamento
401 Falha de autenticação Key errada, Bearer ausente, Key inválida Corrigir credenciais primeiro
404 Caminho ou modelo inexistente Base URL errada, nome antigo, caminho duplicado Verificar endereço e modelo
429 Limite de taxa ou cota Pico de concorrência, Key compartilhada, tempestade de retries Backoff, reduzir concorrência
Timeout Timeout de conexão ou leitura Rede, saída longa, modelo de raciocínio, proxy Diagnosticar por camadas
400 Parâmetros ou contexto inválidos Contexto acima do limite, formato errado Quantificar e dividir
5xx Erro do serviço upstream Falha ou sobrecarga no servidor Backoff, trocar de canal

No log, registre ao menos horário, status code, tipo de erro, nome do modelo, duração e request ID. Não registre a Key completa nem imprima o texto original do usuário inteiro no log.

2. 401: primeiro o cabeçalho, depois a Key

401 indica que a identidade não foi validada; normalmente não tem relação com capacidade do modelo nem saldo. Diagnostique nesta ordem:

  1. O cabeçalho usa Authorization: Bearer <key> e não outro método de autenticação?
  2. Há espaços, quebras de linha ou aspas extras antes ou depois da Key? Copiar de uma janela de chat costuma trazer esses caracteres.
  3. A variável de ambiente foi realmente carregada? Imprimir apenas o prefixo já confirma.
  4. A Key foi excluída, rotacionada ou desativada?
  5. Base URL e Key pertencem à mesma plataforma? Key oficial com endereço de gateway resulta em 401.
  6. O proxy reverso sobrescreveu ou descartou o cabeçalho Authorization?
export DEEPSEEK_API_KEY="sk-sua-chave"

curl "https://api.deepseek.com/chat/completions" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Responda apenas OK"}],
    "max_tokens": 16
  }'

Se este comando retorna 200, Key, Base URL e nome do modelo estão corretos. Se ainda retorna 401, use uma Key nova em uma requisição mínima para distinguir problema da própria Key de problema de configuração do proxy ou gateway.

3. 404: endereço e nome de modelo são os erros mais comuns

404 geralmente não significa "a interface caiu", mas que a requisição chegou a um caminho ou modelo inexistente. Causas comuns:

  • Base URL escrita com endereço de outro fornecedor, ou com /v1 a mais ou a menos.
  • O SDK acrescenta /chat/completions automaticamente e o caminho é montado de novo manualmente.
  • O nome do modelo usa uma versão antiga descontinuada, ou há diferença de maiúsculas e sufixo.
  • Endereço de gateway e endereço oficial misturados, com regras de caminho diferentes.
  • Regra de reescrita do proxy reverso altera o caminho.

No diagnóstico, envie primeiro a URL completa com curl e confira a mensagem de erro no corpo; depois compare Base URL e nome do modelo item a item com a página de preços do site. Não codifique vários endereços no código; configure por ambiente para não levar o endereço de teste para produção.

4. 429: limitação não é saldo insuficiente

429 indica que a requisição excedeu o limite de taxa, concorrência ou cota. O DeepSeek pode limitar ou enfileirar requisições no horário de pico; os critérios específicos seguem a documentação oficial. Cenários comuns:

  • Vários serviços compartilham a mesma Key e disputam a cota.
  • Tarefas em lote iniciam todas na virada da hora, criando picos de tráfego.
  • Retries sem backoff: quanto mais falham, mais tentam, gerando tempestade.
  • Saídas longas ou tarefas de raciocínio consomem mais recursos e reduzem o espaço para concorrência.
Sintoma Causa provável Tratamento
429 concentrado no pico Carga upstream ou pico de tráfego Fila, envio suave, escalonar horários
429 em vários serviços com uma Key Cota compartilhada Separar Keys por projeto
Piora após retries Retry sem backoff Backoff exponencial com jitter
Requisições longas recebem 429 primeiro Alto consumo de tokens de saída Reduzir max_tokens ou concorrência 
import random
import time
from openai import OpenAI, RateLimitError, APITimeoutError, APIStatusError

client = OpenAI(
    api_key="sk-sua-chave",
    base_url="https://api.deepseek.com",
    max_retries=0,  # desative o retry automático do SDK para não somar com o retry customizado
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="deepseek-chat",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
                timeout=60,
            )
            return resp.choices[0].message.content
        except (RateLimitError, APITimeoutError):
            wait = min(2 ** attempt, 20) + random.random()
            print(f"Falha na tentativa {attempt + 1}, aguardando {wait:.1f} s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Número de tentativas esgotado")

print(ask("Explique em uma frase o que é limitação de taxa"))

Retry só serve para erros transitórios. Em operações que já produziram efeitos colaterais, use chave de idempotência ou verificação de estado para confirmar se a ação foi executada antes de decidir reenviar.

5. Timeout: separe conexão, leitura e streaming

Timeout não significa serviço indisponível; primeiro localize em que etapa ele trava:

Sintoma Causa provável Tratamento
Timeout de conexão DNS, saída de rede, proxy inacessível Verificar rede e proxy, trocar de rota
Primeiro token muito lento Fila upstream, prompt longo Encurtar entrada, escalonar, usar modelo leve
Timeout de leitura Saída longa, raciocínio demorado Aumentar timeout de leitura, limitar saída
Interrupção de streaming Oscilação de rede, proxy cortando Suportar reconexão, registrar conteúdo recebido
Timeout geral simultâneo Saída local ou falha upstream Trocar para canal alternativo, ver status 
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="sk-sua-chave",
    base_url="https://api.deepseek.com",
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
)

Timeout de conexão e de leitura devem ser configurados separadamente. Colocar tudo em um valor muito alto trava o pool de threads em caso de falha; muito baixo mata tarefas longas legítimas. Configurar por tipo de tarefa é mais seguro.

6. Tabela de ordem de diagnóstico

  1. Registre status code, tipo de erro, request ID, nome do modelo e horário.
  2. Em 401, verifique Key, cabeçalhos, variáveis de ambiente e compatibilidade de plataforma.
  3. Em 404, verifique Base URL, montagem do caminho e nome do modelo.
  4. Em 400, verifique parâmetros, tamanho do contexto e formato de imagem ou arquivo.
  5. Em 429, verifique concorrência, Keys compartilhadas, política de retry e horário de pico.
  6. Em timeout, verifique DNS, proxy, tamanho da saída e configuração de timeout de leitura.
  7. Em 5xx, faça backoff primeiro; se persistir, contate o provedor com o request ID.
  8. Após cada falha, acrescente monitoramento e alertas; não espere o usuário reclamar.

7. Monitoramento e logs

Campo Uso
Horário e projeto Localizar picos e escopo de impacto
Status code e tipo de erro Distinguir autenticação, limitação e erro upstream
Request ID Credencial-chave para o provedor investigar
Nome e versão do modelo Identificar se surgiu após troca de modelo
Tokens de entrada e saída Analisar custo e requisições longas
Duração e número de retries Detectar latência de cauda e tempestade de retries

Monitore ao menos por hora as contagens de 401, 404, 429, timeout e 5xx. Se a taxa de erro disparar, verifique primeiro se está concentrada em um projeto, uma Key ou um modelo; depois decida entre reduzir concorrência, trocar de canal ou reverter versão.

Perguntas frequentes

429 é saldo insuficiente?

Não. 429 indica que a requisição excedeu o limite de taxa, concorrência ou cota; saldo insuficiente costuma retornar outro erro ou vir explicado no corpo da resposta. Verifique primeiro concorrência e Keys compartilhadas, depois o saldo da conta.

Qual é a causa mais comum de 404?

Base URL errada, caminho montado em duplicidade e nome de modelo expirado. Envie a URL completa com curl e confira o nome do modelo na página de preços; em geral, a causa é localizada em poucos minutos.

Timeout deve ser repetido indefinidamente?

Não. Retry precisa de limite, backoff e alerta; além disso, timeout pode significar que a requisição já foi executada no upstream. Em operações com efeitos colaterais, confirme o estado antes de reenviar.

O que fazer quando o streaming é interrompido?

Registre o conteúdo já recebido e o ponto de interrupção, depois avalie se foi oscilação de rede, corte do proxy ou timeout upstream. O cliente deve suportar reconexão e deduplicação; não salve conteúdo pela metade como resultado completo.

Como distinguir erro do gateway de erro oficial?

Guarde request ID e tipo de erro e envie a mesma requisição tanto à entrada oficial quanto à do gateway. Assim é rápido distinguir problema de Key, rede, configuração do gateway ou serviço upstream.

Próximos passos

Crie uma Key de teste no ZSQH AI Gateway, simule uma vez cada caso — 401, 404, 429 e timeout — e então conecte o monitoramento de produção. Disponibilidade de modelos e preços seguem a página de preços.

Leitura relacionada: