Skip to main content
Se algo der errado com sua chave ou com os limites do plano, a API retorna códigos HTTP claros:
Exemplos: campos obrigatórios ausentes, formato inválido, SMS com menos de 9 caracteres (code: SMS_MESSAGE_TOO_SHORT na API v1), ou outras regras documentadas em cada produto (templates, domínios, etc.).
Verifique se o header está correto e se a chave não foi apagada no painel.
Verifique se a chave tem o Escopo necessário para a rota. Para envio, verifique também créditos/plano (PLAN_LIMIT_CREDITS) ou agendamento não permitido (PLAN_LIMIT_SCHEDULING). Para domínios, limite de domínios do plano (PLAN_LIMIT_EMAIL_DOMAINS).
Renove a assinatura, recarregue saldo/créditos ou aumente o limite da API Key. Códigos: WORKSPACE_BLOCKED, INSUFFICIENT_CREDITS, INSUFFICIENT_CREDITS_OR_BALANCE, API_KEY_SPEND_LIMIT_EXCEEDED.
Confira o ID e se o recurso existe no workspace da chave.
Use o domínio existente ou outro nome.
Tente novamente ou verifique a configuração do provedor.
Contate o suporte ou verifique a configuração do ambiente.

​
Enums de erro (API v1) e como resolver

Além do status HTTP, muitas respostas incluem code (enum) para facilitar tratamento no cliente. Use sempre status + code para decidir retry, correção de payload ou ação de negócio.

​
Autenticação, acesso e onboarding

  • ONBOARDING_REQUIRED
    Significa: a conta/workspace ainda não concluiu onboarding obrigatório.
    Como resolver: finalize o onboarding no painel antes de chamar as rotas protegidas.
  • SCOPE_GROUPS_REQUIRED
    Significa: a API Key não possui escopo para operações de grupos WhatsApp.
    Como resolver: edite/recrie a chave incluindo escopo de grupos (whatsapp:groups).
  • GROUP_FEATURES_DISABLED
    Significa: o workspace não habilitou recursos experimentais de grupos WhatsApp.
    Como resolver: ative groupFeaturesEnabled no workspace e mantenha escopo de grupos na key.

​
Workspace, plano, créditos e fila

  • WORKSPACE_BLOCKED
    Significa: workspace bloqueado por situação de plano/trial/cobrança.
    Como resolver: regularize assinatura/trial/saldo e tente novamente.
  • WORKSPACE_SLOTS_LIMIT_REACHED
    Significa: limite de workspaces por usuário atingido.
    Como resolver: faça upgrade de plano ou remova um workspace existente.
  • LAST_WORKSPACE
    Significa: tentativa de deletar o último workspace do usuário.
    Como resolver: crie outro workspace primeiro; depois exclua o desejado.
  • PLAN_LIMIT_CREDITS
    Significa: o plano não permite a operação naquele contexto (créditos/limite do tier).
    Como resolver: upgrade de plano ou ajuste volume/tipo de envio.
  • INSUFFICIENT_CREDITS
    Significa: créditos insuficientes para concluir o envio.
    Como resolver: aguarde renovação, faça upgrade ou reduza volume.
  • INSUFFICIENT_CREDITS_OR_BALANCE
    Significa: sem créditos e sem saldo suficiente no Pague pelo uso.
    Como resolver: recarregue saldo ou ajuste plano/créditos.
  • API_KEY_SPEND_LIMIT_EXCEEDED
    Significa: a API Key atingiu o teto de gasto configurado.
    Como resolver: aumente/remova o limite da chave ou use outra API Key.
  • WORKSPACE_BACKLOG_SOFT_LIMIT
    Significa: backlog de fila próximo/acima do limite brando.
    Como resolver: reduzir taxa de envio, aplicar retry com backoff e monitorar fila.
  • WORKSPACE_BACKLOG_LIMIT
    Significa: backlog da fila do workspace excedeu o limite duro.
    Como resolver: pausar envios novos, drenar fila e retomar gradualmente.
  • PLAN_LIMIT_SCHEDULING
    Significa: agendamento não está disponível no plano atual.
    Como resolver: enviar imediato ou fazer upgrade para plano com agendamento.
  • PLAN_LIMIT_SCHEDULING_DAYS
    Significa: data de agendamento excede a janela máxima do plano.
    Como resolver: reagendar dentro do limite de dias aceito.
  • PLAN_LIMIT_WEBHOOKS
    Significa: limite de webhooks por workspace atingido.
    Como resolver: remover webhooks não usados ou fazer upgrade.
  • WEBHOOK_CREATE_BUSY
    Significa: criação de webhook bloqueada temporariamente (operação concorrente).
    Como resolver: retry após alguns segundos (backoff exponencial).
  • PLAN_LIMIT_INSTANCES
    Significa: limite de instâncias WhatsApp do plano atingido.
    Como resolver: excluir instâncias inativas ou fazer upgrade.
  • PLAN_LIMIT_PUSH_APPS
    Significa: limite de apps de push do plano atingido.
    Como resolver: remover app não usado ou fazer upgrade.
  • PLAN_LIMIT_EMAIL_DOMAINS
    Significa: limite de domínios de e-mail do plano atingido.
    Como resolver: remover domínio não utilizado ou fazer upgrade.

​
Conteúdo e validação da requisição

  • PAYLOAD_TOO_LARGE
    Significa: payload excedeu tamanho máximo permitido.
    Como resolver: reduzir corpo/anexos/metadata e reenviar.
  • DATA_TOO_LARGE
    Significa: campo data (ex.: push payload) excedeu limite.
    Como resolver: envie menos chaves/bytes no objeto data.
  • METADATA_TOO_LARGE
    Significa: metadados excederam o tamanho aceito.
    Como resolver: compacte/remova campos de metadata.
  • SMS_MESSAGE_TOO_SHORT
    Significa: conteúdo SMS abaixo do mínimo (9 caracteres).
    Como resolver: aumente o texto (mín. 9, máx. 160) antes do envio.
  • SMS_DUPLICATE_RECENT
    Significa: envio detectado como duplicado em janela curta.
    Como resolver: evite retries imediatos idênticos; use idempotência/chaves de deduplicação.
  • CANNOT_SEND_TO_SELF
    Significa: origem e destino representam o mesmo remetente/instância.
    Como resolver: altere o destinatário para um contato válido diferente da origem.

​
WhatsApp, e-mail e push (regras de canal)

  • INSTANCE_ACTIVE
    Significa: tentativa de excluir instância ainda ativa/em uso.
    Como resolver: desconecte/pare a instância e remova vínculos antes de deletar.
  • DOMAIN_NOT_VERIFIED
    Significa: domínio de e-mail ainda não verificado no workspace.
    Como resolver: conclua DNS/verificação e tente novamente.
  • DEFAULT_DOMAIN_NOT_VERIFIED
    Significa: domínio padrão do workspace não está verificado.
    Como resolver: defina um domínio verificado como padrão ou informe from verificado.
  • DOMAIN_NOT_ALLOWED
    Significa: domínio de envio não pertence/permitido para o workspace.
    Como resolver: use domínio cadastrado/verificado nesse workspace.
  • RECIPIENT_SUPPRESSED
    Significa: destinatário bloqueado por supressão (bounce/complaint/unsubscribe).
    Como resolver: remova supressão com consentimento válido ou use outro destinatário.
  • PUSH_APP_NOT_ALLOWED
    Significa: app push informado não está autorizado para o workspace/key atual.
    Como resolver: use um pushAppId do workspace da chave.
  • PLATFORM_NOT_CONFIGURED
    Significa: plataforma push (iOS/Android/Web) não configurada no app.
    Como resolver: configure credenciais da plataforma no app push antes de enviar.
  • ORIGIN_NOT_ALLOWED
    Significa: origem não permitida para registro/operação de device push.
    Como resolver: inclua a origem/domínio na allowlist do app/projeto.

​
Contatos, tags e cancelamento

  • CONTACT_REQUIRES_PHONE_OR_EMAIL
    Significa: contato sem telefone e sem e-mail (mínimo obrigatório).
    Como resolver: informe ao menos um dos campos.
  • CONTACT_PHONE_EXISTS
    Significa: já existe contato com esse telefone no workspace.
    Como resolver: atualize o contato existente ou use outro número.
  • CONTACT_EMAIL_EXISTS
    Significa: já existe contato com esse e-mail no workspace.
    Como resolver: atualize o contato existente ou use outro e-mail.
  • TAG_NOT_FOUND
    Significa: tag informada não existe no workspace.
    Como resolver: crie a tag antes ou corrija o ID.
  • TAG_NAME_EXISTS
    Significa: já existe tag com esse nome no workspace.
    Como resolver: reutilize a existente ou escolha outro nome.
  • CANNOT_CANCEL_PROCESSING
    Significa: mensagem já está em processamento e não pode ser cancelada.
    Como resolver: trate como não-cancelável e acompanhe status final.
  • CANNOT_CANCEL_STATUS
    Significa: status atual da mensagem não permite cancelamento.
    Como resolver: só cancele mensagens em estados elegíveis (antes do processamento final).