“Your client token is not configured” é provavelmente o erro que mais interrompe primeiras integrações com a Z-API, e a boa notícia cabe na primeira frase: ele é um erro de autenticação com correção determinística, não um defeito da instância. A mensagem diz exatamente o que falta; o que confunde é onde esse “client token” mora e por que ele existe separado do token da instância.
TL;DR: O erro “client token is not configured” na Z-API indica que a chamada chegou sem o token de segurança da conta (Client-Token), exigido no header das requisições além das credenciais da instância na URL. Correção: localizar o token de segurança no painel da conta, adicioná-lo como header Client-Token em todas as chamadas e conferir se a ferramenta intermediária (n8n, Make, conector de CRM) tem campo próprio para ele. São dois segredos distintos: o da instância identifica o número; o da conta autoriza o cliente.
Por que existem dois tokens
A arquitetura de autenticação da Z-API usa credenciais em camadas: a URL da chamada carrega os identificadores da instância (o número conectado), e o header carrega o token de segurança da conta, uma proteção adicional para impedir que alguém com a URL vazada opere a sua instância. O erro aparece exatamente quando a segunda camada falta: a chamada identifica a instância, mas não prova que vem de você.
Esse desenho pega de surpresa quem copia exemplos antigos de código (anteriores à obrigatoriedade do header) ou quem migra de outra API que autentica só pela URL.
Correção em três verificações
- Localize o token da conta. No painel da Z-API, na área de segurança da conta, existe o token de conta (Client-Token), distinto do token que aparece na URL da instância. Copie-o sem espaços.
- Envie no header. Toda chamada REST precisa do header
Client-Tokencom esse valor. No Postman ou no módulo HTTP do n8n/Make, é um header adicional; teste uma chamada simples (status da instância) e confirme que o erro sumiu antes de mexer no resto. - Confira as ferramentas intermediárias. Conectores prontos e nós de comunidade têm (ou não) campo para o token de conta. Conector desatualizado que não envia o header produz exatamente este erro, e a correção é atualizar o conector ou trocar a chamada por HTTP direto, o fallback universal que recomendamos em integrações da Z-API.
Se o token está lá e o erro persiste
Três causas residuais, em ordem: token regenerado no painel (alguém girou a chave e as integrações antigas ficaram com a anterior; regenerou, redistribuiu), espaço ou quebra de linha invisível colado junto do valor (reescreva à mão em caso de dúvida), e confusão entre contas (o token é por conta; instância de uma conta com token de outra falha). Persistindo após as três, aí sim é ticket para o suporte, com o request de exemplo anexado, na camada certa do problema, como explicamos no mapa de problemas e limitações da Z-API.
O que este erro ensina sobre a operação
Um detalhe que vale registrar da experiência de operar integrações: erros determinísticos como este são os melhores problemas que uma API de WhatsApp oferece, porque se corrigem uma vez e ficam corrigidos. A categoria inteira dos problemas ruins mora na outra camada, a do vínculo com a plataforma (desconexão, entrega silenciosa, ban), onde não há header que resolva. Quem está montando a operação agora faz bem em resolver o token em dez minutos, e em gastar uma hora entendendo a camada de baixo no nosso guia da Z-API, porque é lá que as decisões de arquitetura se pagam. A versão sem tokens para gerenciar nem camada instável embaixo, com conexão oficial e coexistência, é o Cubo Suite, interesse declarado.
Onde encontro o Client-Token da Z-API?
Na área de segurança da conta no painel da Z-API, separado das credenciais da instância. É um token por conta, aplicado via header em todas as chamadas.
O token da instância e o Client-Token são a mesma coisa?
Não: o token da instância (na URL) identifica o número conectado; o Client-Token (no header) autentica a conta. O erro “not configured” refere-se ao segundo.
Regenerar o Client-Token quebra as integrações?
Sim, todas as que usam o valor antigo, imediatamente. Regenere apenas em suspeita de vazamento, e com plano de redistribuição para cada integração ativa.
Deixe um comentário