Nos erros da Kimi API, olhe primeiro três coisas: código de status HTTP, error.type e request_id. Um mesmo 429 pode ser sobrecarga do servidor, limite da organização ou saldo insuficiente; um mesmo 401 pode ser chave errada ou mistura entre site chinês e internacional. Classifique antes de alterar o código.

Este artigo separa 401, 404, 429 e timeout em quatro categorias, com 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: Moonshot e Kimi são marcas de seus titulares. Tipos de erro, regras de limite e comportamento das interfaces podem mudar; este artigo toma como exemplo a situação comum em outubro de 2026 e tem como referência final a documentação oficial.

1. Consulta rápida de códigos

Código Tipo de erro Significado comum Direção de tratamento
400 invalid_request_error Parâmetro inválido, contexto longo demais, limite de saída excedido Corrigir a requisição
400 content_filter Entrada ou saída acionou segurança de conteúdo Ajustar o prompt
401 invalid_authentication_error Chave inválida, região incompatível Corrigir credencial
401 incorrect_api_key_error Chave ausente ou incorreta Corrigir credencial
403 permission_denied_error Interface não habilitada, lista de IP, saldo ou permissão Verificar permissão e saldo
404 resource_not_found_error Nome do modelo ou caminho errado Consultar lista de modelos
429 engine_overloaded_error Sobrecarga do servidor Backoff e retry
429 rate_limit_reached_error Concorrência, RPM, TPM ou TPD excedidos Reduzir velocidade ou ampliar cota
429 exceeded_current_quota_error Atraso, saldo insuficiente, cupom expirado Recarregar
499 client_closed_request Cliente ou proxy encerrou antes Verificar timeout e streaming
500 server_error Erro interno do servidor Backoff e retry
503 server_unavailable Serviço temporariamente indisponível Backoff e retry
504 Gateway Time-out Requisição longa esperou demais Mudar para streaming

Saldo insuficiente pode aparecer como 403 ou 429 dependendo da entrada; não julgue apenas pelo código, use error.type. Registre no log ao menos horário, código, tipo de erro, nome do modelo e request_id; nunca registre a chave completa nem conteúdo sensível.

2. 401: verifique a região antes da chave

  1. Uma chave do site chinês está configurada com endereço internacional, ou o contrário? As contas, saldos e chaves dos dois sites são totalmente independentes.
  2. Há mistura de chaves de linhas de produto diferentes, como plataforma aberta, Kimi Code e assinatura?
  3. A chave tem espaços, quebra de linha ou aspas extras no início ou no fim?
  4. A variável de ambiente foi realmente carregada? Imprima apenas o prefixo para confirmar.
  5. A chave foi apagada, rotacionada ou não tem permissão no projeto atual?
  6. O cabeçalho é Authorization: Bearer <key> e o caminho é /v1/chat/completions?
export MOONSHOT_API_KEY="sua-chave"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6",
    "max_completion_tokens": 64,
    "messages": [{"role": "user", "content": "Responda apenas OK"}]
  }'

Se este comando retornar 200, chave, região e nome do modelo estão corretos. Se ainda retornar 401, teste com outra chave sabidamente válida para distinguir problema da chave de problema de configuração do gateway.

3. 404: nome do modelo e base_url são os erros mais comuns

Um 404 não significa necessariamente que o modelo saiu do ar; há quatro causas comuns:

  • Ao usar o SDK da OpenAI sem configurar base_url, a requisição vai para o endereço padrão da OpenAI e retorna modelo inexistente.
  • Nome do modelo com erro de grafia, ou modelo ao qual a conta não tem acesso.
  • Caminho com /v1 a mais ou a menos, ou interface de chat escrita em outro caminho.
  • Nomes de modelo e permissões diferentes entre site chinês e internacional.

Primeiro liste os modelos com a mesma chave para confirmar o que a conta enxerga:

curl "https://api.moonshot.cn/v1/models" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY"

Não adivinhe modelos que não aparecem na lista. A disponibilidade segue o retorno real da conta e a página de preços do site. Se a lista retorna mas a interface de chat continua em 404, verifique se falta /v1 no caminho e se o cliente está concatenando base_url com o caminho completo, duplicando o trecho.

4. 429: três tipos, tratamentos diferentes

error.type Significado Pode repetir? Tratamento
engine_overloaded_error Sobrecarga do servidor Sim Backoff conforme Retry-After, reduzir concorrência
rate_limit_reached_error Concorrência, RPM, TPM ou TPD da organização excedidos Em parte Reduzir velocidade, separar chaves, subir de nível
exceeded_current_quota_error Atraso, saldo insuficiente, cupom expirado Não Recarregar ou revisar a fatura

Ao exceder o TPD, normalmente só resta esperar o dia seguinte ou ampliar a cota; continuar repetindo não faz sentido. Requisições interrompidas por 429 normalmente não são cobradas, mas passam a ser cobradas quando o retry tem sucesso; não repita indefinidamente por medo de gastar nem presuma que a conta já foi debitada ao ver 429. O SDK da OpenAI repete automaticamente por padrão, o que pode transformar um 429 em várias requisições; em produção, defina max_retries explicitamente e use sua própria lógica de backoff.

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="sua-chave",
    base_url="https://api.moonshot.cn/v1",
    max_retries=0,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="kimi-k2.6",
                messages=[{"role": "user", "content": prompt}],
                max_completion_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError as exc:
            body = exc.body or {}
            etype = (body.get("error") or {}).get("type", "")
            if etype == "exceeded_current_quota_error":
                raise RuntimeError("Saldo ou cota insuficientes; recarregue primeiro")
            wait = min(2 ** attempt, 20) + random.random()
            print(etype, "aguardando", round(wait, 1), "s")
            time.sleep(wait)
    raise RuntimeError("tentativas esgotadas")

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

5. Timeout e 504

Geração de textos longos, análise de documentos extensos e agentes de código são os cenários mais propensos a timeout. A ordem de tratamento é:

  1. Troque chamadas não streaming por stream=True para manter dados fluindo na conexão.
  2. Defina timeouts de conexão e leitura razoáveis; não use os padrões do SDK sem revisão.
  3. Verifique se proxy corporativo, gateway ou ferramenta de roteamento local encerram a conexão antes; isso pode aparecer como 499.
  4. Controle o tamanho de cada saída com max_completion_tokens e divida tarefas muito longas.
  5. Registre o ID e a duração de cada timeout para distinguir modelo lento, rede lenta e gateway lento.
stream = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[{"role": "user", "content": "Escreva um checklist de implantação"}],
    max_completion_tokens=2048,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Streaming não reduz o preço unitário, mas elimina boa parte do desperdício de "esperar até o timeout e repetir". O timeout de conexão pode ser curto; o de leitura deve seguir o tempo máximo de geração. Em streaming, não reuse o timeout de leitura do modo não streaming, ou o próprio cliente cortará a conexão durante uma geração normal.

6. Uma tabela de ordem de diagnóstico

  1. Registre código de status, error.type, request_id, nome do modelo e horário.
  2. Para 401 e 403, verifique região, chave, linha de produto, permissão e saldo.
  3. Para 404, verifique base_url, nome do modelo e permissão da conta; valide com a lista de modelos.
  4. Para 400, verifique tamanho de contexto, limite de saída, formato de arquivo e segurança de conteúdo.
  5. Para 429, separe por error.type em sobrecarga, limite de taxa e falta de saldo.
  6. Para 499 e 504, verifique streaming, timeout, proxy e manutenção de conexão.
  7. Para 500 e 503, faça backoff e retry; se persistir, envie o request_id ao provedor.
  8. Após cada incidente, melhore monitoramento e alertas; não espere o feedback do usuário.

Perguntas frequentes

Qual é a diferença entre 429 e 503?

O 429 pode ser sobrecarga do servidor, cota da conta ou saldo; veja primeiro error.type. O 503 indica serviço temporariamente indisponível e geralmente pede backoff e retry. Nos dois casos, não repita em intervalos fixos e agressivos.

Depois de recarregar, ainda recebo 401. O que fazer?

Confirme se a recarga e a chave pertencem à mesma região e à mesma linha de produto. Teste com uma chave recém-criada para descartar chave antiga apagada ou cache de variável de ambiente.

Que erro aparece quando o contexto é longo demais?

Normalmente 400 invalid_request_error, com mensagem citando tokens de entrada excessivos. Reduza a entrada, corte o histórico ou use um modelo com contexto maior.

Devo ativar o retry automático do SDK?

Pode ativar, mas com limite. O retry padrão pode amplificar um 429; em produção, recomenda-se desativar o retry automático do SDK e implementar backoff exponencial e alertas por tipo de erro.

Como diferenciar erro do gateway de erro oficial?

Envie a mesma requisição para a conexão direta e para o gateway e compare código, error.type e request_id. Isso ajuda a identificar rapidamente se a causa é upstream, rede, chave ou configuração do gateway.

Próximos passos

Crie primeiro uma chave de teste no ZSQH AI Gateway, simule uma vez cada caso 401, 404, 429 e timeout e depois integre ao monitoramento de produção. Disponibilidade de modelos e preços seguem a página de preços.

Leitura relacionada: