Erros comuns na API de WhatsApp da StackZap e como investigar

Uma resposta de erro da API é o primeiro sinal para identificar o que precisa ser corrigido. Registre o status HTTP, a rota, o horário e a mensagem retornada; remova API Keys e dados pessoais antes de compartilhar um diagnóstico.

401 — credencial

Confira se enviou X-API-Key e se ela pertence ao ambiente chamado.

400 — solicitação

Confira campos obrigatórios, tipos de dados e o formato esperado pelo endpoint.

Verificações por situação

• 401 Unauthorized: confira o header X-API-Key, a origem da chave e se a aplicação está lendo o secret correto.
• 400 Bad Request: valide o JSON, nomes dos campos obrigatórios e o formato do destinatário segundo o schema.
• Instância não conectada: consulte o status e conclua o pareamento antes de repetir o envio.
• 404 Not Found: verifique URL, caminho, ID da instância e se o recurso pertence àquele ambiente.
• 5xx ou timeout: registre a resposta, horário e identificador de correlação disponível; tente novamente com backoff somente depois de avaliar se a operação anterior pode ter sido aceita.

Nem toda operação usa exatamente os mesmos códigos ou textos. Consulte a resposta e o contrato do endpoint específico na documentação da API.

Prepare um diagnóstico útil

Inclua método e caminho da rota, status HTTP, horário com fuso, versão da API, estado da instância e um exemplo de corpo sem informação privada. Nunca envie cabeçalhos de autenticação completos, QR Code, código de pareamento, tokens de callback ou conversas sem necessidade.

No StackZap Cloud, o suporte pode ser aberto pelo widget no canto inferior do painel, pelo e-mail informado na conta ou pelo WhatsApp de atendimento. O horário informado é de segunda a sexta, das 9h às 17h (horário de Brasília).

Monte uma sequência de diagnóstico

Comece reproduzindo a falha com uma única requisição segura e registre ambiente, instância, método, rota, status HTTP, horário com fuso, duração e identificador de correlação. Remova chave, QR Code, código de pareamento, número completo e corpo privado. Uma sequência clara é mais útil do que um arquivo enorme sem contexto.

Separe em camadas: o cliente resolve o host? O TLS é válido? A aplicação chegou ao endpoint? A autenticação passou? O JSON foi aceito? A instância está conectada? A operação foi aceita? Cada resposta aponta para uma área diferente. Um erro DNS ocorre antes da autenticação; um 401 mostra que a API foi alcançada, mas a credencial precisa ser investigada.

Erros de rede e URL

Se a aplicação não resolve o domínio, verifique a URL específica do ambiente e o DNS. Se a conexão falha antes de receber status HTTP, cheque firewall de saída, proxy, TLS, certificado, porta e rota. No Cloud, copie o endereço do painel do ambiente em vez de usar uma URL genérica. No self-hosted, valide o domínio configurado e se a API está publicada como esperado.

Uma URL pode estar válida e ainda apontar para outra instalação. Confira ambiente, caminho, ID e protocolo. Evite adicionar /v1 duas vezes ao combinar base com endpoint. Não exponha hostname interno em resposta ao usuário final; registre-o em logs restritos e compartilhe somente quando necessário ao diagnóstico.

Erros de autenticação e permissão

No 401, confirme o header, o valor, a origem da chave e se a variável está carregada no processo correto. Uma aplicação reiniciada pode continuar usando segredo antigo se o deploy não atualizou a configuração. No 403, verifique escopo, permissão, plano ou regra do endpoint conforme a documentação. Não use credencial de outro ambiente como solução permanente.

Se suspeitar de vazamento, trate como incidente: retire a exposição, avalie logs, siga o mecanismo de revogação ou contate suporte, atualize os serviços e verifique repositórios e artefatos antigos. Nunca cole a chave no pedido de suporte para provar que está correta.

Erros de corpo e validação

Um 400 normalmente exige comparar o JSON com os campos e tipos esperados. Verifique aspas, vírgulas, encoding, nomes de propriedades, campos ausentes e valores nulos. Telefone, URL de arquivo, MIME type e conteúdo podem exigir formatos diferentes por endpoint. Use exemplos atuais da referência e valide antes da chamada.

Evite imprimir o corpo completo se ele contém telefone ou mensagem. Para depurar, substitua dados por valores sintéticos e mantenha estrutura equivalente. Se uma integração funciona com payload mínimo, acrescente um campo por vez até localizar a diferença. Isso torna o problema reproduzível sem expor dados reais.

Erros de estado da instância

Se o envio retorna que a instância não está conectada, consulte o estado e conclua o pareamento pelo painel. Não repita mensagens enquanto aguarda conexão, a menos que seu sistema tenha fila, expiração e deduplicação. Depois da reconexão, valide uma operação controlada e reconcilie itens de resultado incerto.

Se o status mostra conectado mas a chamada falha, confirme que status e envio usam a mesma URL, API Key e ID. Em sistemas com múltiplas instâncias, uma variável errada pode misturar recursos. Registre IDs internos claros e não deduza que instâncias com o mesmo nome pertencem ao mesmo ambiente.

Timeouts e respostas 5xx

Um timeout não informa se o servidor executou a operação. Verifique request ID, retorno, webhook ou estado associado antes de repetir uma ação que possa enviar mensagem. Use timeout no cliente e backoff com limites. Retentativas simultâneas por vários workers podem amplificar uma indisponibilidade; aplique limite de concorrência quando adequado.

Para uma falha 5xx, salve status, duração e ID de requisição, aguarde uma pausa progressiva e tente novamente apenas se a semântica for segura. Não repita erros 4xx permanentes sem modificar a solicitação. Se o problema persistir, abra suporte com um exemplo mínimo e o intervalo afetado.

Duplicidade, ordem e eventos

Uma operação pode ser aceita mesmo que o consumidor não receba a resposta. Webhooks podem ser repetidos e chegar fora de ordem. Mantenha correlação entre evento de negócio, chamada e entrega. Use identificador estável e deduplicação para impedir ação duplicada. Se não conseguir determinar o resultado, marque como incerto e reconcilie antes de reenviar.

O mesmo cuidado vale para ações manuais: clique duplo em botão de envio pode criar duas requisições. Desabilite o controle enquanto a chamada está em andamento e use idempotência no backend. Uma interface responsiva não deve sacrificar o registro confiável da operação.

Diagnóstico para Cloud e self-hosted

No Cloud, confirme URL, ambiente e instância; consulte o widget de suporte quando precisar investigar a plataforma. Informe a faixa de horário e um identificador, sem segredos. No self-hosted, o operador também revisa logs da aplicação, host, banco, proxy, firewall, DNS, recursos e backups. Não compare resultados de versões diferentes sem registrar qual versão foi usada.

Modelo de relatório

Ambiente: homologação
Instância: inst_abc (identificador fictício)
Operação: consultar status
Horário: 2026-10-10 14:20 -03:00
Resultado: HTTP 401, duração 84 ms
Request ID: req_xxx, se disponível
Alteração recente: deploy da variável de ambiente
Segredos e dados pessoais: removidos

O modelo não é um formato oficial, mas contém elementos que tornam o incidente reproduzível. O suporte não precisa receber a API Key para verificar um 401. Antes de anexar logs, pesquise por X-API-Key, assinatura HMAC, telefone e texto de mensagem.

Checklist final

• Reproduziu a falha com uma chamada isolada?
• Separou rede, autenticação, validação e estado?
• Conferiu URL, credencial e instância do mesmo ambiente?
• Avaliou se houve execução antes do timeout?
• Aplicou backoff somente onde repetir é seguro?
• Protegeu dados de contato e credenciais nos logs?
• Informou versão, horário e request ID no chamado?

Use uma árvore curta de decisão

Se não há status HTTP, investigue conectividade, DNS, TLS, proxy e timeout no cliente. Se recebeu 401, confira header e segredo do ambiente. Se recebeu 400, valide corpo e parâmetros. Se a resposta informa instância desconectada, consulte o estado e passe pelo pareamento. Se recebeu 5xx ou timeout durante um envio, determine se a operação pode ter sido aceita antes de repetir. Essa ordem evita trocar credenciais para corrigir DNS ou recriar instâncias por falha de JSON.

Execute uma consulta simples antes de uma ação de envio quando isso ajudar a separar autenticação e disponibilidade. Use a mesma URL base e chave. Não troque várias configurações ao mesmo tempo; faça uma alteração por tentativa e anote o resultado. Em ambiente de produção, prefira comandos de leitura para diagnóstico inicial e teste de envio controlado apenas depois de validar o destinatário.

Localize a camada da falha

Interprete a resposta completa

Status HTTP e corpo de resposta devem ser lidos em conjunto. A chamada pode retornar HTTP válido e um estado de negócio que indique processamento pendente ou uma instância não pronta. Preserve o request ID, código de erro e mensagem técnica documentada, mas traduza a informação para a tela. Não exiba stack trace, hostname privado ou credencial ao usuário final.

Se a resposta mudar entre versões, valide a documentação correspondente antes de atualizar parser. Um parser que assume texto fixo pode quebrar quando a API altera uma frase mantendo o código. Prefira campos estáveis do schema e trate erros desconhecidos como não classificados, com log sanitizado.

Faça uma captura segura para reproduzir

Monte um exemplo mínimo com o mesmo método, rota e estrutura, usando ambiente de teste e dados sintéticos. Remova o header de autenticação e coloque placeholder no comando antes de compartilhar. Preserve somente o campo necessário para reproduzir a falha. Se o problema depende de mídia, troque por arquivo de teste pequeno e sem dados pessoais.

Não envie uma coleção completa de Postman exportada sem revisar secrets, variáveis e exemplos. Não copie cookies do navegador ou cabeçalhos de sessão. Revise também o terminal: um comando cURL com API Key pode estar salvo no histórico local.

Aprenda com a resolução

Depois de resolver, registre a causa raiz em uma nota operacional: sintoma, camada afetada, correção, versão e prevenção. Evite guardar valores de credenciais ou conversas. Se a causa foi URL trocada, valide configuração por ambiente no deploy; se foi retry duplicado, adicione deduplicação; se foi estado desconectado, crie alerta e runbook.

Um catálogo de erros recorrentes ajuda atendimento e desenvolvimento a responder de forma consistente. Mantenha links para os manuais atuais e uma data de revisão. Não transforme um caso pontual numa regra geral sem evidência; diferencie comportamento confirmado da hipótese que ainda precisa de observação.

Diferencie erro de cliente e incidente de serviço

Uma falha isolada de payload costuma apontar para a integração que fez a chamada. Aumento simultâneo de timeout ou 5xx em várias operações pode indicar problema mais amplo. Compare chamadas de leitura e escrita, ambientes e horários, sem concluir causa apenas por um gráfico. No Cloud, informe a janela de impacto ao suporte. No self-hosted, verifique telemetria e dependências locais.

Use um identificador de correlação por chamada e propague-o ao seu serviço interno, sem inventar header StackZap não documentado. Isso permite acompanhar backend, fila e resultado sem colocar o telefone ou a chave no log. Caso a API forneça request ID, guarde-o separadamente do ID do seu evento.

Resolva falhas em ordem de risco

Comece com operações de leitura e ambientes de teste. Não reinicie serviços, apague instâncias ou remova volumes como primeiro passo. Antes de qualquer ação que altera dados, confirme seu efeito na documentação e verifique backup. Durante incidente ativo, registre cada mudança e quem a executou; várias correções simultâneas podem ocultar a causa ou piorar o impacto.

Depois da correção, valide a operação que falhou com um exemplo controlado, acompanhe a taxa de erro e reconcilie tarefas que ficaram em resultado incerto. Fechar o alerta sem revisar a fila pode deixar mensagens pendentes ou duplicadas.

Perguntas rápidas

Devo tentar novamente quando recebo timeout?

Primeiro determine se a operação pode ter sido aceita. Consulte retorno, ID, status do job ou webhook disponível. Se ainda não for possível confirmar, marque como resultado incerto e reconcilie; repetir imediatamente pode duplicar a mensagem.

O que enviar ao suporte?

Informe ambiente, ID da instância, rota, status, horário com fuso e request ID, se houver. Inclua passos para reproduzir usando dados de teste. Remova API Key, assinatura HMAC, QR, telefone completo e conteúdo de conversa.

Um HTTP 200 confirma entrega?

Não necessariamente. Ele descreve o resultado HTTP daquela chamada. Verifique o estado de negócio e os eventos documentados para saber o que ocorreu depois. Não prometa ao usuário final entrega ou leitura com base apenas no código HTTP.

Quando procurar a equipe Cloud?

Se URL, autenticação e payload estão corretos, mas o erro persiste ou afeta várias operações, forneça uma linha do tempo sanitizada pelo widget no painel do ambiente. Para self-hosted, primeiro reúna dados do host e dependências que você administra.