GLM Coding Plan com cota, mas cobrando do saldo: como corrigir
Diferencie chaves Standard, Coding Plan e Compatible antigas, identifique a origem da cobrança e investigue erros 429 de cota, acesso e limite de uso.
Uma assinatura GLM Coding Plan não faz todas as chaves da sua conta consumirem a cota do plano. Para chaves Standard e Coding Plan criadas a partir de 16 de outubro de 2026, a Z.ai informa que o tipo de chave determina a cobrança nos endpoints compatíveis. Chaves Compatible antigas seguem outras regras, que dependem do endpoint.
Essa distinção explica por que “ainda tenho cota” pode coexistir com uma dedução do saldo ou uma requisição malsucedida. Este guia oferece uma ficha de rota e chave, um classificador de erros e um procedimento de verificação controlada. Ele se baseia na documentação oficial conferida em 17 de novembro de 2026; não executamos experimentos pagos de cobrança nem inspecionamos sua conta.
O artigo amplia nosso conjunto de guias sobre GLM. Ele não anuncia GLM 5.5: o índice público oficial verificado hoje ainda lista a família GLM-5.3. Para essa questão separada, veja nossa verificação de lançamento e disponibilidade do GLM 5.5. Não substitua o identificador de uma configuração funcional por um glm-5.5 presumido.
Identifique a classe da chave no console
Use o guia de gerenciamento de chaves da Z.ai para identificar a chave configurada no processo real da ferramenta. Confira o rótulo no console e o contexto de criação, não a aparência da sequência secreta. Uma conta pode conter várias classes de chave ao mesmo tempo.
| Classe no console | Origem | Regra de cobrança a investigar |
|---|---|---|
| Standard API Key | Opção de criação de chave Standard | Saldo da conta ou pacotes de uso aplicáveis, não a cota do Coding Plan |
| Personal Coding Plan API Key | Opção de Coding Plan pessoal | Cota do Individual Plan |
| Team Plan Key | Team Coding Plan → My Plan | Regras do Team Plan e das licenças, incluindo política configurada de uso excedente |
| Chave Compatible antiga | Chave antiga classificada automaticamente | Endpoint e histórico de plano da conta determinam o comportamento |
O aviso de 16 de outubro informa que os valores das chaves existentes não precisam ser substituídos apenas pela mudança de classificação. Chaves antigas associadas a um projeto Team Plan tornam-se chaves Team Plan; chaves pessoais antigas elegíveis de contas que já tiveram um Coding Plan tornam-se Compatible. Contas antigas sem esse histórico recebem a classificação Standard. Exceções específicas de contratos empresariais ou canais parceiros podem manter suas regras contratadas.
Não comece o diagnóstico trocando todas as chaves. Primeiro descubra qual é realmente usada: uma variável exportada no terminal, configuração de IDE, projeto ou ferramenta de troca de provedor pode ainda apontar para uma credencial antiga. Registre apenas um rótulo não secreto do console ou um identificador interno. Nunca cole a chave completa em um chamado ou captura de tela pública.
Aplique a regra correta para o endpoint
Para chaves Standard e Coding Plan novas, mudar entre endpoints compatíveis não altera o tipo de cobrança. Uma chave Standard no Claude Code pode consumir saldo de API mesmo quando um Coding Plan ativo ainda tem cota. Para consumir a cota do plano, use a chave correspondente e uma configuração de ferramenta compatível.
Para uma chave Compatible antiga, o aviso da Z.ai descreve o seguinte comportamento por rota:
| URL base | Protocolo ou uso | Comportamento da chave Compatible |
|---|---|---|
https://api.z.ai/api/paas/v4 | Chat Completions padrão | Saldo ou pacotes de uso aplicáveis; não usa a cota do Coding Plan |
https://api.z.ai/api/coding/paas/v4 | Chat Completions do Coding Plan | Cota do plano se a conta já teve um plano; chamadas param quando ele expira |
https://api.z.ai/api/anthropic | Anthropic Messages | Mesma regra de histórico do plano na tabela oficial de chaves Compatible |
https://api.z.ai/api/v1 | OpenAI Responses | Mesma regra de histórico do plano na tabela oficial de chaves Compatible |
O aviso também descreve cobrança por saldo ou pacotes nas últimas rotas para contas que nunca tiveram Coding Plan. Se a classificação do console não corresponder a esse cenário, não conclua apenas pela URL; peça ao suporte que reconcilie a classificação da chave e o registro da requisição. Uso excedente de equipes e contratos empresariais específicos exigem sua própria verificação na conta.
Essas rotas são da Z.ai. Elas não descrevem a conta do serviço chinês BigModel nem a cobrança de terceiros. Uma chave Ofox segue o contrato de autenticação do Ofox, não sua assinatura Z.ai. Confira a disponibilidade de modelos no Ofox e a documentação do provedor antes de mudar. Não copie as URLs da tabela para uma configuração Ofox.
Rastreie uma requisição do cliente ao registro de uso
Crie uma ficha curta antes de alterar qualquer coisa:
Client and version:
Process actually launched (CLI / IDE / container):
Provider and Base URL:
Protocol (Messages / Chat Completions / Responses):
Exact model ID or alias mapping:
Key class shown in provider console (NO secret value):
Plan active? Remaining quota? Team overage enabled?:
Local timestamp and time zone:
HTTP status / business code / sanitized request ID:
Usage record and billing bucket after the test:
Pause outras sessões de teste para não contaminar a comparação. Registre as visualizações relevantes de uso do plano e saldo e, só se autorizar o possível custo, faça uma pequena requisição sem dados sensíveis. Por exemplo, peça ao modelo configurado que retorne apenas READY, sem ferramentas nem acesso ao repositório. Isso verifica uma chamada básica; não é um teste de qualidade.
Depois, reconcilie o horário do cliente, o identificador da requisição quando disponível, o modelo selecionado e o registro de uso do provedor. Uma resposta bem-sucedida, por si só, não comprova de onde saiu a cobrança. Considere o atraso de atualização do painel. Se a atribuição continuar incerta, interrompa novos experimentos e guarde evidências sem dados sensíveis para o suporte, em vez de gerar uma sequência de chamadas pagas.
Considere três resultados ilustrativos, não medidos:
- Uma chave Standard nova no Claude Code funciona e aparece no uso de API padrão. Isso é compatível com a regra documentada mesmo se ainda houver cota do plano.
- Uma chave Compatible antiga funciona no endpoint padrão de Chat Completions e consome saldo. Alterar apenas a rota dessa chave antiga pode mudar a origem da cobrança, mas isso não se aplica de forma geral a chaves Standard novas.
- Uma chave Compatible com plano expirado falha em uma rota do plano. O aviso diz que ela não muda automaticamente para pagamento por uso. Para usar deliberadamente a cobrança de API, crie uma chave Standard e use-a em um endpoint compatível, com saldo suficiente. É uma escolha de cobrança, não uma alternativa gratuita.
Para uma chave recém-criada, substitua-a pela classe correta, reinicie o processo real do cliente e repita uma verificação controlada. Para uma chave Compatible, decida primeiro entre cobrança pelo plano ou pela API padrão e aplique a regra documentada. Não mude chave, endpoint, modelo e política de repetição ao mesmo tempo: você perderá a evidência de qual mudança resolveu o problema.
Leia o código de negócio dentro do 429
A referência de códigos de erro da Z.ai associa HTTP 429 a várias causas. Um loop genérico de espera exponencial não resolve todas elas.
| Código de negócio | Categoria documentada | Resposta útil |
|---|---|---|
1113 | Saldo ou pacote de recursos insuficiente | Confira a origem da cobrança e os fundos; não presuma que a cota do plano se aplica |
1302 | Limite de requisições | Reduza a concorrência e use backoff com limite |
1305 | Sobrecarga temporária | Repita com uma política limitada; registre falhas persistentes |
1308, 1310 | Limites de janela de uso | Leia a informação de reinício retornada; não deduza o horário pela meia-noite local |
1309 | Coding Plan expirado | Confira o plano e escolha uma renovação autorizada ou uma rota de API padrão deliberada |
1311 | Plano sem acesso ao modelo escolhido | Confira o direito de acesso e o mapeamento exato |
1313 | Restrição de uso justo | Siga o processo de suporte do provedor; mais chaves não são uma solução alternativa |
1315 | Chave restrita a cenários empresariais de programação | Use a chave do produto e a configuração de conta adequadas |
1316–1321 | Janela de uso mais condição de saldo ou limite de gastos para uso extra | Leia a mensagem exata; confira elegibilidade para excedentes e limites configurados antes de alterar gastos |
Erros de autenticação são um ramo separado: por exemplo, 1000 e 1001 estão associados a HTTP 401 na referência. Aumentar a cota não corrige a ausência do cabeçalho de autenticação. Por outro lado, substituir repetidamente uma chave válida não reativa um plano expirado.
Para classificar localmente uma resposta de erro salva, grave o código abaixo como classify_glm_error.py. Ele lê JSON da entrada padrão e imprime apenas o código e uma categoria de diagnóstico, sem a mensagem da resposta nem credenciais.
import json
import sys
categories = {
"1000": "authentication", "1001": "authentication",
"1003": "authentication", "1005": "authentication",
"1113": "billing-balance", "1302": "request-rate",
"1305": "temporary-overload", "1308": "usage-window",
"1309": "plan-expired", "1310": "usage-window",
"1311": "model-entitlement", "1313": "fair-usage",
"1314": "enterprise-plan-expired", "1315": "key-product-mismatch",
}
categories.update({str(n): "extra-usage-condition" for n in range(1316, 1322)})
data = json.load(sys.stdin)
error = data.get("error", {}) if isinstance(data, dict) else {}
code = str(error.get("code", "unknown")) if isinstance(error, dict) else "unknown"
print(json.dumps({"code": code, "category": categories.get(code, "inspect-provider-response")}))
Uma verificação local sintética:
printf '%s\n' '{"error":{"code":"1311","message":"synthetic example"}}' | python3 classify_glm_error.py
A categoria esperada é model-entitlement. Testamos esse classificador localmente, incluindo códigos numéricos e objetos de erro ausentes. Ele não diagnostica falhas de rede, não normaliza formatos específicos de gateways nem substitui a leitura da mensagem exata do provedor. Um resultado desconhecido exige inspecionar a estrutura da resposta; não significa que a requisição teve sucesso. Para encerramentos anormais durante um stream SSE, a Z.ai documenta o motivo da exceção em finish_reason, em vez desses códigos comuns de erro. Salve e examine os eventos do stream separadamente; esse classificador JSON não interpreta SSE.
Confira a seleção do modelo depois de corrigir a cobrança
Quando chave e rota estiverem corretas, verifique o mapeamento exato do modelo de forma independente. O guia oficial de troca de modelos atualmente documenta GLM-5.3 e GLM-5.3-Flash. Nível de assinatura, alias do cliente como Opus e identificador público de API de um modelo são coisas distintas.
Se o cliente informar que um modelo está ausente, compare o identificador configurado e o protocolo com a documentação atual do provedor. Nosso guia de erros “model not found” da OpenAI (em inglês) traz verificações de provedor e endpoint que ajudam a distinguir um nome incorreto de acesso indisponível. Para controlar o ritmo de requisições em rotas Ofox, use a documentação de limites de requisições do Ofox; não aplique esses limites a contas Z.ai por analogia.
Não use um nome especulativo de GLM 5.5 para testar se seu plano funciona. Comece por um modelo explicitamente disponível para a conta e a rota. Só depois de aprovar uma chamada básica e sua atribuição de cobrança, teste execuções longas de agentes, ferramentas ou extensões de contexto.
Encerre o incidente com evidências, não com outro loop de tentativas
Um caso resolvido deve identificar a classe da chave, o endpoint pretendido, o modelo aceito e a origem real da cobrança, e mostrar que o erro relevante parou com a configuração corrigida. Preserve as configurações anteriores para reverter mudanças sem recriar segredos.
Se os registros do provedor contradisserem a regra documentada, envie ao suporte horário com fuso, ID da requisição sem dados sensíveis, classe da chave, modelo e código de erro. Não envie a credencial completa nem conteúdo privado do prompt sem um motivo aprovado separadamente e um canal seguro. Isso permite investigar a cobrança sem transformar o diagnóstico em mais uma série incerta de requisições.
Perguntas frequentes
- Trocar a URL base faz uma chave Standard nova consumir a cota do Coding Plan?
- Não. Segundo a Z.ai, o tipo das chaves Standard ou Coding Plan criadas a partir de 16 de outubro de 2026 determina a cobrança nos endpoints compatíveis. Chaves Compatible antigas seguem regras diferentes.
- Todo HTTP 429 do GLM significa que devo tentar novamente depois?
- Não. O código de negócio do provedor pode indicar saldo, cota, plano vencido, acesso ao modelo ou limite de requisições. Corrija a causa indicada antes de repetir a chamada.


