Troubleshooting
Diagnóstico rápido por código e sintoma.
Erros da Partner API
| Código / sintoma | Causa provável | Correção |
|---|---|---|
invalid_instance_id | external_customer_id enviado como UUID | Use instance_key ou UUID real |
route_not_found | Rota ausente/incorreta | GET usa ?route=...; POST usa body route |
partner_access_denied | Credencial não pertence ao partner | Revise API key/JWT e recurso |
billing_access_restricted | Assinatura past_due/restrita | Atualize o cartão e aguarde sincronização |
remote_callback_removal_failed | Meta não removeu callback | Corrija credencial e tente novamente |
credential_not_found | Token Meta não persistido | Faça reconnect após corrigir onboarding |
webhook_url_https_required | URL não HTTPS | Use endpoint público com TLS válido |
template_refresh_rate_limited | Refresh dentro do cooldown | Use cache e aguarde next_allowed_at |
Falha de capacidade ao conectar ou reconectar
Uma falha de verificação não significa falta de vaga. O sistema deve distinguir capacidade, cobrança e operações concorrentes antes de sugerir qualquer mudança de plano.
| HTTP / código | Significado | Como orientar |
|---|---|---|
409 number_capacity_unavailable / slot_limit_reached | Não há vaga disponível para admitir o número. | Confira os números em uso, as reservas e as reduções agendadas. Se etapas na Meta já ocorreram, consulte o resultado antes de repetir a tentativa. |
503 number_capacity_check_unavailable | A capacidade não pôde ser verificada. | Não confirma limite atingido. Comprar outro pacote não resolve essa falha. Atualize a sessão e procure o suporte se persistir. |
409 connection_update_in_progress | Outra operação está atualizando a conexão ou a capacidade. | Aguarde e consulte o estado atual. Não refaça OAuth nem recomende pacote adicional. |
402 billing_payment_required | A assinatura precisa ser regularizada. | O parceiro responsável deve conferir Planos e cobrança. O cliente final não administra a assinatura HookCloud. |
409 billing_sync_required | O período confirmado da assinatura terminou e precisa ser atualizado. | O parceiro deve conferir a assinatura no Portal. Este aviso não confirma recusa do cartão nem falta de vagas. |
500 instance_update_failed / slot_sync_failed | O registro final na HookCloud não pôde ser confirmado após etapas na Meta. | Consulte a sessão e a instância. Não reutilize o código OAuth nem repita a autorização. Acione o suporte se a pendência continuar. |
Nos erros de admissão, error.retryable=false impede repetição automática, inclusive nos HTTP 500 e 503. error.details.retryable=false também pode aparecer quando details estiver presente; não dependa desse bloco nos erros de servidor. É preciso conferir o resultado antes de decidir a próxima ação. Não significa que a falha seja definitiva. Use get-partner-instance no seu backend; a própria página Connect pode atualizar sua sessão. Preserve o request_id para suporte, sem registrar tokens.
Reconectar a mesma instância já contabilizada não consome outra vaga. Uma instância desconectada que liberou a capacidade só pode voltar a ocupá-la quando houver vaga disponível. Identidade, risco e cobrança continuam sendo verificados.
GET retorna health check em vez da instância
Use:
GET https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-instance&instance_id=UUIDNão use /swift-worker/get-partner-instance como formato oficial no domínio customizado.
Connect Flow não fecha
Abra o link com window.open. Navegadores podem impedir window.close() quando a página foi aberta diretamente em uma aba.
Webhook não recebe mensagens
- Confira
remote_callback_status=active. - Teste o GET de verificação.
- Confirme que o endpoint responde 2xx.
- Verifique se o app está inscrito na WABA.
- Confirme o
phone_number_id. - Revise firewall, TLS e redirects.
Referência: Webhook Subscriptions
Template não aparece
- Confirme WABA e idioma.
- Consulte sem
sendable_only. - Veja o status da sincronização.
- Solicite refresh uma única vez.
- Confirme o template no WhatsApp Manager.
Mensagem aceita, mas não entregue
O POST pode retornar um waMID e a entrega falhar depois. Use o webhook statuses. Os erros 131049 e 131042 exigem ações diferentes; consulte Saúde de Entregas.
O que enviar ao suporte
- Data/hora UTC
- partner_id
- instance_id / instance_key
- phone_number_id
- route
- HTTP status
- error.code e fbtrace_id
- Sem tokens ou conteúdo de mensagem
Lifecycle de cliente e reconnect
| Código | Significado | Ação |
|---|---|---|
partner_customer_inactive | O cliente está inativo/arquivado/mesclado. | Chame reactivate-partner-customer antes de gerar connect/reconnect. |
customer_deactivation_partial_failure | Uma ou mais instâncias não concluíram o hard disconnect. | Leia results[], corrija a credencial/callback e repita. Instâncias já inativas são tratadas de forma idempotente. |
meta_registration_rate_limited | Meta 133016: muitas tentativas de registro/desregistro. | Não repita. Aguarde o cooldown informado e gere uma nova sessão. |
meta_send_access_revocation_failed | Não foi possível garantir o bloqueio de envio. | Não considere a inativação concluída; revise token compartilhado e credencial Meta. |
Notificações não aparecem
- Confirme que o membro está ativo e usando JWT, não Partner API Key.
- Abra Configuração e confira se a categoria está habilitada.
popup_enabled=falseoculta apenas o toast; o item ainda pode aparecer no sino.- Para lembretes financeiros, confirme que o Cron da fila Stripe está ativo.
- Alertas Meta de teste com IDs fictícios podem ficar sem partner e não aparecem no Portal.