Os erros do GLM API têm duas camadas: o status HTTP externo e o código de negócio no corpo da resposta. Olhar só a camada externa induz a erro facilmente; por exemplo, conta em atraso também retorna 429. A ordem de diagnóstico deve ser: ler primeiro o código de negócio e a mensagem, localizar o request ID ou error ID, reproduzir com uma requisição mínima e só então alterar parâmetros ou trocar de modelo.

Este artigo separa 401, 403, 404, 429, 5xx e timeout, e apresenta a tabela de códigos de negócio, código de tratamento de erros e um checklist para antes de contatar o suporte. Modelos e preços seguem a página de preços do site.

Nota: Zhipu, GLM e BigModel são marcas registradas de seus titulares. Este artigo é apenas uma explicação técnica e não implica vínculo de subordinação ou representação com a Zhipu. Códigos de erro, critérios de limitação e comportamento da interface podem mudar entre versões; vale a documentação oficial e a resposta real.

1. Distinga primeiro as duas camadas de erro

O status HTTP descreve o resultado no nível do protocolo; o código de negócio descreve a causa específica. O mesmo 401 pode significar cabeçalho de autenticação ausente, token expirado ou autenticação secundária; o mesmo 429 pode ser limitação de taxa, modelo ocupado, conta em atraso ou teto do plano. Registrar o código de negócio no log é o passo mais eficiente do diagnóstico.

HTTP Código de negócio comum Significado Indicado repetir?
401 1000 / 1001 / 1003 / 1005 Falha de autenticação, cabeçalho ausente, token expirado, autenticação secundária Não; corrigir credencial
403 1220 Sem permissão para acessar a API ou o modelo Não; verificar plano e permissão
400 1210 / 1211 / 1221 / 1222 / 1261 Parâmetro errado, modelo inexistente, API descontinuada ou inexistente, prompt longo demais Não; ajustar requisição
429 1113 Conta em atraso Não; recarregar primeiro
429 1302 / 1305 Limite de taxa, volume de acesso ao modelo alto Sim; backoff e retry
429 1308 / 1310 Teto periódico, reinicia em next_flush_time Aguardar reset; não insistir
429 1311 / 1313 / 1315 Plano sem permissão de modelo, limite de uso justo, tipo de Key incompatível Não; verificar plano e Key
500 1200 / 1230 / 1234 Erro interno, falha de fluxo, erro de rede (com error ID) Sim; backoff e guardar o error ID

A tabela mostra os mapeamentos mais comuns; a lista completa segue a documentação oficial. Interrupção de streaming pode não ter código de negócio, e a causa aparece em finish_reason ou no último trecho de dados.

2. 401: quatro tipos de falha de autenticação

401 indica que a identidade não foi validada e normalmente não tem relação com capacidade do modelo nem saldo. Os códigos oficiais detalham as causas comuns:

  • 1000 falha de autenticação: Key errada, cópia incompleta ou já excluída.
  • 1001 cabeçalho sem parâmetro de autenticação: falta Authorization: Bearer <key> ou o proxy descartou.
  • 1003 token expirado: a Key tem validade ou foi rotacionada no console.
  • 1005 autenticação secundária ativada: conclua a verificação exigida pela plataforma.

Diagnostique nesta ordem:

  1. Confirme o formato do cabeçalho: um espaço após os dois-pontos e sem aspas ou quebras de linha ao redor da Key.
  2. Imprima o prefixo da variável de ambiente para confirmar que não está vazia nem com valor antigo.
  3. Confirme o tipo de Key: API de modelo padrão, Coding Plan, equipe ou empresa são gerenciados separadamente e não podem ser misturados.
  4. Confirme se Base URL e Key pertencem ao mesmo lugar: Key oficial com endereço oficial, Key de gateway com endereço de gateway.
  5. Troque por uma Key nova em uma requisição mínima para separar problema de Key de problema de proxy ou gateway.

Copiar a Key de uma janela de chat é a forma mais comum de trazer espaços ou quebras de linha. Fazer primeiro uma requisição que só devolve uma palavra elimina a maioria dos erros básicos.

3. 403 e 404: permissão, caminho e nome de modelo

O código de negócio mais comum do 403 é 1220, indicando que a conta atual não tem permissão para acessar a API ou o modelo. Verifique se o plano inclui o modelo, se a Key pertence ao tipo de produto correto e se não foi chamada uma interface não liberada. Repetir não resolve esse tipo de erro; ajuste a permissão ou troque de Key.

Na maioria das vezes, 404 não significa "o serviço caiu", mas endereço errado: Base URL com /v1 a mais ou a menos, SDK que monta automaticamente e código que escreve o caminho completo de novo, regra de reescrita do proxy que altera o caminho. No GLM, nome de modelo errado normalmente retorna 400 com 1211; API descontinuada ou inexistente corresponde a 1221 e 1222. Portanto, diante de 404 verifique o endereço; diante de 1211, o nome do modelo.

O nome do modelo segue a documentação oficial e a página de preços do site; não escreva números de versão de memória. Ao atualizar de modelo, confirme primeiro a compatibilidade de parâmetros no ambiente de teste.

4. 429: leia o código de negócio antes de decidir repetir

429 é o erro mais sujeito a tratamento errado. Ele cobre ao menos cinco situações:

  • 1113 conta em atraso: repetir antes de recarregar não faz sentido.
  • 1302 limite de taxa atingido: reduzir concorrência ou fazer backoff.
  • 1305 volume de acesso ao modelo alto no momento: normalmente ligado ao pico; backoff e retry, trocando de modelo se necessário.
  • 1308 e 1310 teto periódico de uso atingido: a mensagem traz o horário de reset; aguarde a cota voltar.
  • 1309, 1311, 1313, 1315: plano vencido, modelo não liberado, limite de uso justo ou tipo de Key incompatível; só mudar a configuração resolve.

Somente limitações transitórias como 1302 e 1305 são adequadas para retry automático; nos demais casos, repetir só prolonga a falha. Os critérios de limitação — concorrência, requisições por minuto ou taxa de tokens — variam com plano e modelo; siga o console e a documentação oficial.

5. 5xx e timeout: localize separadamente

A série 500 inclui 1200 erro interno, 1230 falha de fluxo e 1234 erro de rede. O 1234 normalmente traz error ID; guarde-o ao contatar o suporte. Diante de 5xx persistente, faça backoff primeiro, depois verifique o status do serviço ou avisos do provedor; não repita em alta frequência.

Timeout deve ser analisado em três trechos: timeout de conexão é DNS, saída ou proxy inacessível; primeiro token lento geralmente é fila upstream ou entrada longa; timeout de leitura costuma ser saída longa ou raciocínio demorado. O tratamento é diferente para cada caso; não basta aumentar o tempo limite.

Quando uma requisição de streaming é interrompida, pode não haver nem código HTTP nem código de negócio. Registre o conteúdo recebido e o último trecho de dados, verifique finish_reason e então avalie se foi oscilação de rede, corte do proxy ou timeout upstream. Não salve conteúdo pela metade como resultado completo.

6. Request ID e logs: evidências do diagnóstico

A resposta oficial não necessariamente fornece o mesmo nome de request ID em todas as interfaces; o nome do campo segue a resposta real e a documentação. Em engenharia, é mais seguro registrar em duas vias: o cliente gera um trace_id que atravessa todos os retries e, ao mesmo tempo, salva o corpo de erro retornado pelo upstream e qualquer campo request id ou error id exatamente como vieram.

O log deve conter ao menos: horário, trace_id, Base URL, nome do modelo, status HTTP, código de negócio, mensagem de erro, duração, número de retries e se foi streaming. Registre a Key apenas com os primeiros caracteres ou hash; não grave o texto original do usuário nem a resposta completa em disco.

Esses campos não servem só para você. Ao contatar o suporte, um registro com trace_id, código de negócio e requisição mínima de reprodução é muito mais útil do que dizer "às vezes dá erro".

7. Retry e backoff: exemplo de código

O código abaixo desativa o retry automático do SDK, decide se repete pelo código de negócio e imprime trace_id, status e código juntos. Timeout de rede é tratado à parte, com limite de tentativas.

import os
import random
import time
import uuid

import httpx
from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError

client = OpenAI(
    api_key=os.environ["GLM_API_KEY"],
    base_url=os.environ.get(
        "GLM_BASE_URL", "https://open.bigmodel.cn/api/paas/v4"
    ),
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
    max_retries=0,  # desativa o retry automático do SDK; a lógica abaixo controla tudo
)

RETRYABLE_CODES = {1302, 1305}  # limite de taxa e modelo ocupado; atraso e teto de plano ficam fora

def ask(prompt: str, max_attempts: int = 4) -> str:
    trace_id = uuid.uuid4().hex[:12]
    for attempt in range(1, max_attempts + 1):
        try:
            resp = client.chat.completions.create(
                model=os.environ["GLM_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except APIStatusError as exc:
            code = None
            try:
                code = int(exc.response.json().get("code"))
            except Exception:
                pass
            print(
                f"trace={trace_id} attempt={attempt} "
                f"http={exc.status_code} code={code} "
                f"body={exc.response.text[:500]}"
            )
            retryable = exc.status_code >= 500 or (
                exc.status_code == 429 and code in RETRYABLE_CODES
            )
            if not retryable or attempt == max_attempts:
                raise
        except (APITimeoutError, APIConnectionError) as exc:
            print(f"trace={trace_id} attempt={attempt} err={type(exc).__name__}")
            if attempt == max_attempts:
                raise
        wait = min(2 ** (attempt - 1), 20) + random.uniform(0, 1)
        time.sleep(wait)
    raise RuntimeError("Tentativas esgotadas")

Três regras adicionais: respeite preferencialmente o Retry-After retornado pelo servidor, se houver; controle o orçamento de retries globalmente para evitar sobreposição entre serviços; e, em requisições com efeitos colaterais, confirme o estado com chave de idempotência antes de decidir reenviar.

8. Governança de concorrência: mais eficaz do que aumentar retries

Problemas de limitação normalmente não se resolvem com retry, mas com governança na entrada:

  • Defina Key e teto de concorrência independentes por serviço.
  • Fragmente e escalone tarefas em lote para evitar picos na virada da hora.
  • Use filas para suavizar picos; tarefas com falha vão para fila de atraso, não ficam girando no lugar.
  • Monitore a proporção de 429 e a latência P95; ao disparar, reduza primeiro a concorrência.
  • Prepare modelo ou entrada alternativa, mas confirme a compatibilidade de parâmetros antes de trocar.

Os critérios de teto de concorrência, requisições por minuto e taxa de tokens variam com plano e modelo; siga o console e a documentação oficial. Não copie números de outras pessoas; configure pelos seus resultados medidos.

9. Checklist antes de contatar o suporte

  1. Horário e fuso do incidente, e se as falhas ocorreram em bloco.
  2. Base URL, caminho da interface, nome do modelo e método da requisição.
  3. Status HTTP, código de negócio e mensagem de erro completa.
  4. Error ID ou request ID; se não houver, forneça o trace_id gerado por você.
  5. Uma requisição curl mínima reproduzível, com a Key anonimizada.
  6. Se era streaming, se usava contexto longo e se a configuração acabou de mudar.
  7. Escopo de impacto: uma Key, um projeto ou todos os serviços.

Com esses itens prontos, o suporte consegue localizar diretamente, sem idas e vindas. Após cada incidente, acrescente monitoramento e alertas; não espere o usuário reclamar.

10. Perguntas frequentes

1. Todo 429 é limitação de taxa?

Não. 429 também pode ser conta em atraso (1113), teto periódico (1308, 1310), plano sem permissão de modelo (1311) ou limite de uso justo (1313). Leia primeiro o código de negócio e então decida entre backoff, recarga ou mudança de configuração.

2. Troquei a Key e o 401 continua. O que fazer?

Verifique se o cabeçalho é Authorization: Bearer <key>, se a variável de ambiente foi carregada, se o tipo de Key corresponde à interface, se Base URL e Key pertencem ao mesmo lugar e se o proxy reverso está descartando o cabeçalho de autenticação.

3. Timeout deve ser repetido?

Faça retry limitado apenas em falha de conexão e timeout de leitura, com backoff exponencial. Em operações com efeitos colaterais, confirme primeiro se já foram executadas para evitar pedidos ou gravações duplicadas.

4. Como diagnosticar streaming interrompido no meio?

Registre o conteúdo recebido, o último trecho de dados e finish_reason para distinguir oscilação de rede, corte do proxy e timeout upstream. O cliente deve suportar reconexão e deduplicação; não salve conteúdo pela metade.

5. E se a mensagem de erro trouxer só o status, sem código de negócio?

Guarde o corpo e os cabeçalhos completos da resposta, registre trace_id, Base URL, nome do modelo e requisição mínima de reprodução e contate o provedor. Ao usar gateway, forneça também esses dados ao gateway para facilitar a correlação com os logs upstream.

Próximos passos

Crie uma Key de teste no ZSQH AI Gateway, simule uma vez cada caso — 401, 403, 429, 5xx e timeout — e então conecte o monitoramento de produção. Modelos disponíveis e formas de cobrança estão na página de preços.

Leitura relacionada