Respostas de Erro

Erro na API é o semáforo vermelho do caminho: o HTTP diz a gravidade e o code diz o que parou. Trate pelo code, não pela mensagem em texto livre.

O que é uma resposta de erro?

Quando algo dá errado, a API responde com um código HTTP e um campo code estável no JSON. Use os dois para decidir se corrige o pedido, tenta de novo ou avisa o usuário. Pense como o painel do carro: a luz acende (HTTP) e o manual diz o problema (code).

Para que serve?

Com as respostas de erro você pode:

Automatizar tratamento no seu código (retry, mensagem ao usuário, alerta interno)
Depurar mais rápido com Logs da API
Evitar depender de texto traduzido em message

Formato padrão

Em toda a API v1, erros vêm assim:

{
  "success": false,
  "error": "Bad Request",
  "message": "Texto legível para humanos",
  "code": "BAD_REQUEST"
}

Campo	O que é
error	Rótulo HTTP (ex.: `Bad Request`)
message	Texto legível, localizado via `Accept-Language` / `x-locale` quando aplicável
code	Enum estável, sempre presente. É a fonte principal para o seu código

Em templates, erros de variável podem trazer também missingVariables (chaves {{…}} que faltaram) e details (array { field, message } por campo).

Desde jul/2026 todos os erros HTTP da API v1 incluem code + message. Integrações antigas que só liam message devem migrar para code.

Códigos HTTP mais comuns

400: algo no pedido está errado

Campo faltando, formato inválido, remetente ambíguo no body, etc. Corrija o body e tente de novo.

401: chave inválida ou ausente

Header errado, chave revogada ou expirada. Confira Authorization: Bearer sk_.... Em linha oficial WhatsApp, token Meta expirado/inválido também pode vir como 401 com META_TOKEN_EXPIRED / META_TOKEN_INVALID (chave ok; reconecte a instância).

402: plano, créditos ou limite de gasto

Trial acabou, saldo zerado ou teto da chave estourado. Recarregue, faça upgrade ou ajuste o limite da chave.

403: sem permissão

Escopo faltando, recurso fora da lista da chave ou operação bloqueada. Ajuste escopos ou restrições da chave.

404: não encontrado

ID errado, instância inativa ou recurso de outro workspace. Confira o ID na URL ou no body.

409: conflito

Recurso duplicado ou estado inválido (ex.: apagar instância ativa; domínio de e-mail já cadastrado, EMAIL_DOMAIN_ALREADY_REGISTERED). Use o existente ou mude o estado antes.

422: recusado pelo provedor

O pedido está bem formado, mas o provedor externo recusou a operação. Em POST /v1/email/domains, domínio bloqueado por antispam ou recusa do provedor de e-mail retorna EMAIL_DOMAIN_PROVIDER_ANTISPAM ou EMAIL_DOMAIN_PROVIDER_REJECTED. Trate pelo code; use message (traduzido) para o usuário final.

429: muitas requisições

Rate limit da API, limite diário do sandbox (SANDBOX_DAILY_LIMIT) ou limite diário do Trust Factor (TRUST_DAILY_LIMIT). Espere, reduza volume ou melhore a pontuação do workspace. Veja Trust Factor.

502 / 503: problema temporário

Instância desconectada ou falha temporária no provedor. Tente de novo em alguns minutos. No registro de domínio de e-mail, indisponibilidade do provedor usa EMAIL_DOMAIN_PROVIDER_UNAVAILABLE (502 ou 503). Não confunda com antispam (422).

Situações especiais

Alguns fluxos não seguem o padrão “HTTP de erro”. Vale guardar estes casos:

Verificar domínio de e-mail (`POST /v1/email/domains/:id/verify`)

Escopos: email:domains:list ou email:domains:create.

Situação	HTTP	`code`	Notas
DNS ainda pendente	200	`EMAIL_DOMAIN_DNS_PENDING`	`success: true`, `verified: false`. Corpo inclui `verificationSummary` e `data.verification`
Domínio verificado	200	`EMAIL_DOMAIN_VERIFIED`	`success: true`, `verified: true`
DNS falhou	200	`EMAIL_DOMAIN_VERIFY_FAILED`	`success: true`, `verified: false`. `verificationSummary` descreve o que falhou
Domínio não encontrado	404	`EMAIL_DOMAIN_NOT_FOUND`
Provedor indisponível	502 / 503	`EMAIL_DOMAIN_VERIFY_UNAVAILABLE`
Configuração ausente no provedor	503	`EMAIL_DOMAIN_MISSING_PROVIDER_KEY`

Denúncias FELCA (`POST /v1/report`)

Endpoint público (sem API Key). Erros seguem o mesmo envelope success: false com code. Guia completo: API de denúncias (FELCA).

Download de mídia WhatsApp inbound

GET /v1/whatsapp/messages/inbound/{id}/media/download ou POST .../media. Escopo whatsapp:read. Tipos: image, audio, document, video, sticker (instância QR). Veja Mensagens recebidas e respostas.

Download de mídia Telegram inbound

GET /v1/telegram/messages/inbound/{id}/media/download ou POST .../media. Escopo telegram:read. Tipos: image, audio, video, document, sticker (Bot e User/QR).

Download de mídia Instagram inbound

GET /v1/instagram/messages/inbound/{id}/media/download ou POST .../media. Escopo instagram:read. Tipos: image, video, audio/voice.

Sending Pools (WhatsApp)

Guia: Sending Pools.

`code`	HTTP	O que fazer
`SENDING_POOL_KIND_MISMATCH`	400	Pool é oficial ou não oficial, não misture tipos ao adicionar instância
`SENDING_POOL_KIND_MIXED`	400	Pool já inconsistente; corrija no painel antes de enviar
`SENDING_POOL_NOT_FOUND`	404	Pool em `from` inválido ou de outro workspace
`SENDING_POOL_UNAVAILABLE`	503	Pool sem instâncias ativas no momento
`ROUTING_CONFLICT`	400	Remetente ambíguo ou conflitante no body

Campanhas com pool: CAMPAIGN_SENDING_POOL_INVALID (seção Campanhas abaixo).

Proteção de número (WhatsApp)

Guia: Política anti-banimento.

`code`	HTTP	O que fazer
`PHONE_NUMBER_MISMATCH`	409	Número escaneado ≠ o esperado ou vinculado, use o chip certo ou nova instância
`RECONNECT_COOLDOWN`	429	Aguarde `retryAfterSec` após queda involuntária antes de novo código
`WARMUP_DAILY_LIMIT`	429	Limite diário nos primeiros 3 dias (20/dia), envie amanhã ou aguarde warm-up

Grupos (WhatsApp, não oficial)

Guia: Grupos. Só instância não oficial.

`code`	HTTP	O que fazer
`SCOPE_GROUPS_REQUIRED`	403	Inclua escopo `whatsapp:groups` na chave
`WHATSAPP_GROUPS_UNOFFICIAL_ONLY`	400	Use instância não oficial, oficial não suporta grupos

Linha oficial Meta (WhatsApp)

Guia: Templates oficiais Meta. Em sk_live_ os gates Meta rodam; no sandbox (sk_test_) não.

`code`	HTTP	O que fazer
`META_TEMPLATE_REQUIRED`	400	Fora da janela 24h, envie template aprovado ou espere resposta do cliente
`META_TEMPLATE_NOT_FOUND`	400	Nome/idioma não bate com a Meta, sync/vínculo; confira `metaName`
`META_TEMPLATE_MEDIA_REQUIRED`	400	Header ou carrossel exige mídia no template oficial
`META_TEMPLATE_CAROUSEL_INCONSISTENT`	400	Cards do carrossel com estrutura diferente, alinhe no editor
`META_PAYMENT_METHOD_REQUIRED`	402	Cadastre cartão no gerenciador do WhatsApp
`META_TOKEN_EXPIRED`	401	Reconecte a instância oficial (token Graph expirado)
`META_TOKEN_INVALID`	401	Reconecte a instância oficial (token inválido)
`META_PERMISSION_DENIED`	403	Permissões Meta insuficientes na conta ou WABA
`META_MESSAGE_EDIT_UNSUPPORTED`	400	Linha oficial não edita mensagem já enviada
`META_MESSAGE_DELETE_UNSUPPORTED`	400	Linha oficial não apaga mensagem já enviada

Publicação e sincronização de templates (API v1)

Endpoints: POST /v1/whatsapp/instances/{instanceId}/meta/push-template (publicar) e POST .../meta/sync-templates (preview/apply). Todas as falhas retornam { success: false, error, message, code } com message localizado via Accept-Language / x-locale.

`code`	HTTP	O que fazer
`TEMPLATE_EMPTY`	400	Preencha o corpo WhatsApp antes de publicar
`TEMPLATE_INVALID`	400	Revise estrutura do template (componentes inválidos)
`TEMPLATE_AUTH_OTP_BUTTON_REQUIRED`	400	Templates AUTHENTICATION exigem botão OTP (copiar código)
`TEMPLATE_ALREADY_EXISTS`	409	Nome+idioma já existem na conta; edite ou renomeie
`TEMPLATE_INVALID_CATEGORY`	400	Use UTILITY, MARKETING ou AUTHENTICATION
`TEMPLATE_INCORRECT_CATEGORY`	400	Categoria não combina com o conteúdo
`TEMPLATE_VARIABLES_INVALID`	400	Preencha exemplos para cada `{{variável}}`
`TEMPLATE_MEDIA_NOT_READY`	400	Aguarde upload/processamento da mídia do cabeçalho
`GUPSHUP_TEMPLATE_PENDING`	409	Template em análise; aguarde aprovação/rejeição
`GUPSHUP_TEMPLATE_NOT_EDITABLE`	409	BSP não sincronizou status rejeitado; tente em alguns minutos
`META_TEMPLATE_DELETION_PENDING`	409	Meta ainda excluindo versão anterior; aguarde ~1 min
`META_TEMPLATE_UPDATE_FAILED`	400	Limite de 1 edição/24h em template aprovado
`META_SYNC_FAILED`	400	Falha ao listar/sincronizar catálogo; reconecte a instância
`TEMPLATE_PUBLISH_FAILED`	422	Falha genérica; revise conteúdo e tente de novo

Lista completa dos códigos de publicação na seção Templates abaixo (TEMPLATE_*, GUPSHUP_*, META_TEMPLATE_CREATE_FAILED, …).

Lista completa de enums (`code`)

Todos os 307 valores code públicos retornados pela API v1. Enums internos da plataforma não entram aqui. Expanda cada seção para ver a tabela. Para o request exato que gerou o erro, abra Logs da API.

Sandbox (1)

`code`	Significado
`SANDBOX_DAILY_LIMIT`	Limite diário do sandbox (50/dia UTC)

Conta e workspace (7)

`code`	Significado
`API_KEY_EXPIRED`	API Key expirada
`API_KEY_REVOKED`	API Key revogada
`LAST_WORKSPACE`	Não pode apagar o único workspace
`ONBOARDING_REQUIRED`	Onboarding incompleto
`UNAUTHORIZED`	API Key ausente ou inválida
`WORKSPACE_HEADER_NOT_ALLOWED`	Header X-Workspace-Id não permitido
`WORKSPACE_SLOTS_LIMIT_REACHED`	Limite de workspaces da conta

Plano, créditos e fila (20)

`code`	Significado
`API_KEY_SPEND_LIMIT_EXCEEDED`	Limite de gasto da API Key estourado
`INSUFFICIENT_CREDITS`	Créditos insuficientes
`INSUFFICIENT_CREDITS_OR_BALANCE`	Sem créditos nem saldo em reais
`PLAN_LIMIT_AUTOMATIONS`	Limite de automações do plano
`PLAN_LIMIT_CREDITS`	Limite de créditos do plano
`PLAN_LIMIT_CRM`	Limite de CRM do plano
`PLAN_LIMIT_EMAIL_DOMAINS`	Limite de domínios de e-mail
`PLAN_LIMIT_INSTANCES`	Limite de instâncias do plano
`PLAN_LIMIT_PUSH_APPS`	Limite de apps push
`PLAN_LIMIT_SCHEDULING`	Agendamento indisponível no plano
`PLAN_LIMIT_SCHEDULING_DAYS`	Data além do limite do plano
`PLAN_LIMIT_TEMPLATES`	Limite de templates do plano
`PLAN_LIMIT_WEBHOOKS`	Limite de webhooks do plano
`PREMIUM_AUTOMATIONS_ACCESS_CODE`	Premium automations access code
`PREMIUM_FEATURE_REQUIRES_PLAN_OR_BALANCE`	Recurso premium exige plano pago, trial ou saldo
`RATE_LIMIT_EXCEEDED`	Limite de requisições excedido
`RATE_LIMIT_SOFT_THRESHOLD`	Rate limit próximo do teto
`WORKSPACE_BACKLOG_LIMIT`	Fila do workspace cheia
`WORKSPACE_BACKLOG_SOFT_LIMIT`	Fila perto do limite
`WORKSPACE_BLOCKED`	Workspace bloqueado (trial ou plano)

WhatsApp (25)

`code`	Significado
`CANNOT_CANCEL_PROCESSING`	Mensagem já em envio
`CANNOT_CANCEL_STATUS`	Status não permite cancelamento
`CANNOT_SEND_TO_SELF`	Destinatário é o próprio número
`EVOLUTION_GO_LICENSE_REQUIRED`	Licença da conexão WhatsApp não oficial ausente/inválida no ambiente
`INSTANCE_ACTIVE`	Instância ainda conectada
`INSTANCE_CHANNEL_MISMATCH`	Canal da instância incompatível
`INSTANCE_NOT_FOUND`	Instância não encontrada ou inativa
`INSTANCE_SMS_NOT_ENABLED`	SMS não habilitado na instância
`INSTANCE_UNAVAILABLE`	Instância WhatsApp incompatível ou inativa para download de mídia
`NO_MEDIA`	Mensagem inbound sem mídia para download
`NO_WHATSAPP_INSTANCE`	Nenhuma instância WhatsApp ativa
`PHONE_NUMBER_MISMATCH`	Número escaneado ≠ lockedPhoneNumber ou expectedPhoneNumber
`RECONNECT_COOLDOWN`	Cooldown de 6 h após desconexão involuntária ou excesso de QR
`ROUTING_CONFLICT`	instanceId e sendingPoolId no mesmo envio
`SCOPE_GROUPS_REQUIRED`	Escopo whatsapp:groups necessário
`SENDING_POOL_KIND_MISMATCH`	Tentativa de misturar instâncias oficiais e não oficiais no mesmo pool
`SENDING_POOL_KIND_MIXED`	Pool já mistura oficial e não oficial; homogeneíze antes de enviar
`SENDING_POOL_NOT_FOUND`	Sending pool não encontrado
`SENDING_POOL_UNAVAILABLE`	Pool sem instâncias ativas
`UNSAFE_CONTENT`	Conteúdo inseguro bloqueado
`WARMUP_DAILY_LIMIT`	Limite warm-up WhatsApp (20 msgs/dia nos primeiros 3 dias)
`WHATSAPP_CALL_UNOFFICIAL`	Whatsapp call unofficial
`WHATSAPP_GROUPS_UNOFFICIAL_ONLY`	Grupos só na conexão não oficial
`WHATSAPP_PRESENCE_FAILED`	Falha ao enviar presença
`WHATSAPP_PRESENCE_GO_ONLY`	Presença disponível só em instâncias compatíveis

SMS (4)

`code`	Significado
`SMS_ALL_SKIPPED`	Todos destinatários SMS ignorados
`SMS_DUPLICATE_RECENT`	SMS duplicado recente
`SMS_MESSAGE_TOO_SHORT`	SMS com menos de 9 caracteres
`UNSAFE_SMS_CONTENT`	Conteúdo SMS bloqueado por política

E-mail (17)

`code`	Significado
`DEFAULT_DOMAIN_NOT_VERIFIED`	Domínio padrão não verificado
`DOMAIN_NOT_ALLOWED`	Domínio fora da lista da chave
`DOMAIN_NOT_VERIFIED`	Domínio de e-mail não verificado
`EMAIL_DOMAIN_ALREADY_REGISTERED`	Domínio de e-mail já cadastrado no workspace
`EMAIL_DOMAIN_CREATE_BUSY`	Cadastro do domínio já em andamento
`EMAIL_DOMAIN_DNS_PENDING`	DNS do domínio ainda pendente
`EMAIL_DOMAIN_MISSING_PROVIDER_KEY`	Email domain missing provider key
`EMAIL_DOMAIN_NOT_FOUND`	Domínio de e-mail não encontrado neste workspace
`EMAIL_DOMAIN_PROVIDER_ANTISPAM`	Provedor bloqueou o domínio (antispam)
`EMAIL_DOMAIN_PROVIDER_REJECTED`	Provedor recusou o domínio
`EMAIL_DOMAIN_PROVIDER_UNAVAILABLE`	Provedor de e-mail indisponível
`EMAIL_DOMAIN_VERIFIED`	Domínio verificado com sucesso
`EMAIL_DOMAIN_VERIFY_FAILED`	Verificação DNS falhou
`EMAIL_DOMAIN_VERIFY_UNAVAILABLE`	Email domain verify unavailable
`EMAIL_TEMPLATE_RESULT_TOO_LONG`	Resultado do template longo demais
`INVALID_LIST_UNSUBSCRIBE_TOPIC`	listUnsubscribeTopicId não é um tópico deste workspace
`RECIPIENT_SUPPRESSED`	Destinatário em supressão (bounce/opt-out)

Instagram (14)

`code`	Significado
`INSTAGRAM_ABUSE_PAUSE`	Pausa após please_wait / feedback_required / abuso
`INSTAGRAM_ACCOUNT_MISMATCH`	Conta logada ≠ locked/expected na instância
`INSTAGRAM_COMMENT_DELETE_FAILED`	Instagram comment delete failed
`INSTAGRAM_COMMENT_HIDE_FAILED`	Instagram comment hide failed
`INSTAGRAM_COMMENT_HIDE_OFFICIAL_ONLY`	Instagram comment hide official only
`INSTAGRAM_COMMENT_REPLY_FAILED`	Instagram comment reply failed
`INSTAGRAM_INSTANCE_NOT_FOUND`	Instância Instagram não encontrada
`INSTAGRAM_META_EDIT_NOT_SUPPORTED`	Instagram meta edit not supported
`INSTAGRAM_META_UNSEND_NOT_SUPPORTED`	Instagram meta unsend not supported
`INSTAGRAM_RECONNECT_COOLDOWN`	Cooldown após queda involuntária ou excesso de logins
`INSTAGRAM_SESSION_LOST`	Sessão Instagram morta; instância desconectada
`INSTAGRAM_TEMPLATE_EMPTY`	Template Instagram renderizou vazio
`INSTAGRAM_TERMS_REQUIRED`	Termos do Instagram pendentes no login
`INSTAGRAM_WARMUP_DAILY_LIMIT`	Limite warm-up Instagram (15 DMs/dia nos primeiros 5 dias)

Telegram (19)

`code`	Significado
`CONTACT_TELEGRAM_PEER_EXISTS`	Peer Telegram já existe no contato
`DUPLICATE_TELEGRAM_INSTANCE`	Instância Telegram duplicada
`INVALID_TELEGRAM_INSTANCE`	Instância Telegram inválida
`INVALID_TELEGRAM_LINKS`	Links Telegram inválidos
`INVALID_TELEGRAM_PEER`	Peer Telegram inválido
`TELEGRAM_BOT_PENDING_TOKEN`	Telegram bot pending token
`TELEGRAM_BOT_TOKEN_INVALID`	Token do bot inválido
`TELEGRAM_INSTANCE_NOT_FOUND`	Telegram instance not found
`TELEGRAM_INSTANCE_REQUIRED`	Instância Telegram obrigatória
`TELEGRAM_QR_CANCEL_NOT_APPLICABLE`	Cancelamento de QR não aplicável
`TELEGRAM_QR_LOGIN_IN_PROGRESS`	Login por QR em andamento
`TELEGRAM_SESSION_ALREADY_SET`	Sessão Telegram já definida
`TELEGRAM_TEMPLATE_CAPTION_TOO_LONG`	Legenda do template longa demais
`TELEGRAM_TEMPLATE_MESSAGE_TOO_LONG`	Texto do template longo demais
`TELEGRAM_TYPE_UNSUPPORTED`	Tipo de mensagem não suportado
`TELEGRAM_USER_INVALID_STATE`	Estado inválido da sessão Telegram
`TELEGRAM_USER_LOCATION_UNSUPPORTED`	Localização não suportada no Telegram
`TELEGRAM_USER_PENDING_SESSION`	Sessão Telegram pendente
`TELEGRAM_USER_TERMS_REQUIRED`	Termos do Telegram pendentes

Push (6)

`code`	Significado
`DATA_TOO_LARGE`	Payload data do push grande demais
`ORIGIN_NOT_ALLOWED`	Origem não permitida
`PLATFORM_NOT_CONFIGURED`	Plataforma não configurada
`PUSH_APP_ID_REQUIRED`	Push app id required
`PUSH_APP_NOT_ALLOWED`	App push fora da lista da chave
`PUSH_APP_NOT_FOUND`	Push app not found

RCS (1)

`code`	Significado
`PAYLOAD_TOO_LARGE`	Body da requisição grande demais

Templates (17)

`code`	Significado
`LOCALIZATION_AI_NOT_SUPPORTED_OFFICIAL_TEMPLATE`	IA não suportada em template Meta oficial
`TEMPLATE_ALREADY_EXISTS`	Template com mesmo nome/idioma já existe na conta
`TEMPLATE_AUTH_OTP_BUTTON_REQUIRED`	Template autenticação sem botão OTP
`TEMPLATE_AUTH_OTP_BUTTON_VARIABLES`	Template auth otp button variables
`TEMPLATE_CHANNEL_NOT_ENABLED`	Canal não habilitado no template
`TEMPLATE_CREATE_BUSY`	Criação de template em andamento
`TEMPLATE_EMPTY`	Corpo WhatsApp vazio ao publicar na Meta
`TEMPLATE_INCORRECT_CATEGORY`	Categoria não combina com o conteúdo
`TEMPLATE_INVALID`	Template não montável para envio à Meta
`TEMPLATE_INVALID_CATEGORY`	Categoria inválida (use UTILITY/MARKETING/AUTHENTICATION)
`TEMPLATE_MEDIA_NOT_READY`	Mídia do cabeçalho não está pronta
`TEMPLATE_META_GROUP_REVIEWING`	Contas do grupo ainda em análise na Meta
`TEMPLATE_NOT_ALLOWED_FOR_INSTANCE`	Template incompatível com a instância WhatsApp
`TEMPLATE_NOT_FOUND`	Template não encontrado
`TEMPLATE_PUBLISH_FAILED`	Falha genérica ao publicar template na Meta
`TEMPLATE_VARIABLES_INVALID`	Variáveis ou exemplos inválidos no template
`TEMPLATE_WABA_PERMISSION_DENIED`	Template waba permission denied

Campanhas (27)

`code`	Significado
`CAMPAIGN_AUDIENCE_TOO_LARGE`	Audiência da campanha grande demais
`CAMPAIGN_CHANNEL_NOT_IN_TEMPLATE`	Canal não habilitado no template
`CAMPAIGN_CONTACT_NOT_FOUND`	Contato da campanha não encontrado
`CAMPAIGN_EMAIL_DOMAIN_NOT_VERIFIED`	Campaign email domain not verified
`CAMPAIGN_FROM_EMAIL_INVALID`	Campaign from email invalid
`CAMPAIGN_FROM_EMAIL_REQUIRED`	Campaign from email required
`CAMPAIGN_INSTAGRAM_INSTANCE_REQUIRED`	Campaign instagram instance required
`CAMPAIGN_PUSH_APP_INVALID`	Campaign push app invalid
`CAMPAIGN_PUSH_APP_REQUIRED`	Campaign push app required
`CAMPAIGN_RUNNING`	Campanha já em execução
`CAMPAIGN_RUNS_SCHEDULED`	Campanha com execuções agendadas
`CAMPAIGN_RUN_RUNNING`	Execução da campanha em andamento
`CAMPAIGN_SCHEDULE_INVALID`	Agendamento de campanha inválido
`CAMPAIGN_SEGMENT_NOT_FOUND`	Segmento da campanha não encontrado
`CAMPAIGN_SENDING_POOL_INVALID`	Sending pool inválido na campanha
`CAMPAIGN_TELEGRAM_INSTANCE_REQUIRED`	Instância Telegram obrigatória na campanha
`CAMPAIGN_TEMPLATE_EMAIL_EMPTY`	Campaign template email empty
`CAMPAIGN_TEMPLATE_INSTAGRAM_EMPTY`	Campaign template instagram empty
`CAMPAIGN_TEMPLATE_PUSH_EMPTY`	Campaign template push empty
`CAMPAIGN_TEMPLATE_RCS_EMPTY`	Campaign template rcs empty
`CAMPAIGN_TEMPLATE_REQUIRED`	Template obrigatório na campanha
`CAMPAIGN_TEMPLATE_SMS_EMPTY`	Campaign template sms empty
`CAMPAIGN_TEMPLATE_TELEGRAM_EMPTY`	Campaign template telegram empty
`CAMPAIGN_TEMPLATE_WHATSAPP_EMPTY`	Campaign template whatsapp empty
`CAMPAIGN_WHATSAPP_INSTANCE_INVALID`	Instância WhatsApp inválida na campanha
`CAMPAIGN_WHATSAPP_INSTANCE_REQUIRED`	Campaign whatsapp instance required
`CAMPAIGN_WHATSAPP_ROUTING_CONFLICT`	Conflito de roteamento WhatsApp na campanha

Contatos e tags (6)

`code`	Significado
`CONTACT_EMAIL_EXISTS`	E-mail já cadastrado no workspace
`CONTACT_NOT_FOUND`	Contato não encontrado
`CONTACT_PHONE_EXISTS`	Telefone já cadastrado no workspace
`CONTACT_REQUIRES_PHONE_OR_EMAIL`	Informe telefone ou e-mail do contato
`TAG_NAME_EXISTS`	Nome de tag já existe
`TAG_NOT_FOUND`	Tag não encontrada

Segmentos (4)

`code`	Significado
`SEGMENT_PROPERTY_NOT_FOUND`	Propriedade do segmento não encontrada
`SEGMENT_TAG_NOT_FOUND`	Tag do segmento não encontrada
`SEGMENT_TOPIC_NOT_FOUND`	Tópico do segmento não encontrado
`TOPIC_SLUG_EXISTS`	Slug de tópico já existe

Automações (grafo) (47)

`code`	Significado
`BRANCH_INVALID`	Ramo inválido no grafo
`CALL_ASSISTANT_COMPOSED_EMPTY`	Resposta composta do assistente vazia
`CALL_ASSISTANT_MANUAL_EMPTY`	Resposta manual do assistente vazia
`CONDITION_BRANCHES`	Ramificações de condição inválidas
`CONDITION_BRANCH_DUP`	Ramo de condição duplicado
`CONDITION_BRANCH_TAG`	Tag de ramo de condição inválida
`CONDITION_CONVERSATION_KEY`	Chave de conversa inválida na condição
`CONDITION_INBOUND_SOURCE`	Origem inbound inválida na condição
`CONDITION_MESSAGE_TRIGGER`	Gatilho de mensagem inválido na condição
`CONDITION_OPERATOR`	Operador de condição inválido
`CONDITION_PROPERTY`	Propriedade de condição inválida
`CONDITION_RUN_ARTIFACT_CHECK`	Verificação de artefato inválida
`CONDITION_RUN_ARTIFACT_KIND`	Tipo de artefato inválido
`CONDITION_RUN_ARTIFACT_REF`	Referência de artefato inválida
`CONDITION_SOURCE`	Origem de condição inválida
`CONDITION_VALUE`	Valor de condição inválido
`CREATE_CONTACT_RECIPIENT`	E-mail ou telefone obrigatório para criar contato
`DELAY_INCOMPLETE`	Passo de espera incompleto
`DUPLICATE_STEP_KEY`	stepKey duplicado no grafo
`END_FLOW_LEAF`	Passo de fim de fluxo deve ser folha
`GRAPH_CYCLE`	Ciclo no grafo de automação
`INVALID_GRAPH`	Grafo de automação inválido
`MCP_APPROVAL_CHECKPOINT_BRANCHES`	Ramificações de checkpoint MCP inválidas
`ROUTER_BRANCHES`	Ramificações do roteador inválidas
`ROUTER_BRANCH_DUP`	Ramo do roteador duplicado
`ROUTER_BRANCH_TAG`	Tag de ramo do roteador inválida
`ROUTER_DEFAULT`	Ramo padrão do roteador inválido
`SEND_EMAIL_INCOMPLETE`	Passo de e-mail incompleto
`SEND_PUSH_INCOMPLETE`	Passo de push incompleto
`SEND_TELEGRAM_INCOMPLETE`	Passo de Telegram incompleto
`SEND_TEMPLATE_ID`	Passo sendTemplate sem template
`SEND_TEXT_INCOMPLETE`	Passo de texto incompleto
`SEND_WHATSAPP_INCOMPLETE`	Passo de WhatsApp incompleto
`TRIGGER_COUNT`	Grafo deve ter exatamente um gatilho
`TRIGGER_NOT_ROOT`	Gatilho deve ser raiz do grafo
`UNKNOWN_STEP`	Passo desconhecido no grafo
`UNREACHABLE_STEP`	Passo inalcançável no grafo
`UPDATE_CONTACT_CLEAR_CUSTOM`	Erro ao limpar propriedade customizada
`UPDATE_CONTACT_EMPTY`	Nada para atualizar no contato
`UPDATE_CONTACT_FIELD`	Campo de contato inválido
`UPDATE_CONTACT_INTENT`	Intenção de atualização inválida
`UPDATE_CONTACT_VALUE`	Valor de contato inválido
`WAIT_SIGNAL_BRANCHES`	Ramificações de espera inválidas
`WAIT_SIGNAL_BRANCH_DUP`	Ramo de espera duplicado
`WAIT_SIGNAL_BRANCH_TAG`	Tag de ramo de espera inválida
`WAIT_WEBHOOK_EVENT_NAME`	Nome de evento de espera inválido
`WIDGET_NOT_FOUND`	Widget não encontrado

Eventos de automação (10)

`code`	Significado
`EVENT_IN_USE`	Evento em uso por automação
`EVENT_NOT_DEFINED`	Evento não cadastrado no workspace
`EVENT_NOT_REGISTERED`	Evento não registrado
`INVALID_EVENT_NAME`	Nome de evento inválido
`INVALID_EVENT_SCHEMA`	Schema do evento inválido
`INVALID_PAYLOAD`	Payload do evento deve ser um objeto JSON
`MISSING_PAYLOAD_FIELD`	Campo obrigatório faltando no payload do evento
`PAYLOAD_TYPE_MISMATCH`	Tipo de campo inválido no payload do evento
`RECIPIENT_REQUIRED`	Informe exatamente um de contactId, email ou phone
`RESERVED_EVENT`	Nome de evento reservado (prefixo notifique:)

Webhooks (5)

`code`	Significado
`WEBHOOK_CREATE_BUSY`	Criação de webhook em andamento
`WEBHOOK_DELIVERY_NOT_FOUND`	Entrega de webhook não encontrada
`WEBHOOK_DISABLED`	Webhook desativado
`WEBHOOK_EVENTS_REQUIRED`	Pelo menos um evento é obrigatório no webhook
`WEBHOOK_NOT_FOUND`	Webhook não encontrado

Links curtos (11)

`code`	Significado
`CONFLICT`	Conversão já registrada
`MSG_ID_REQUIRED`	Campo msg_id obrigatório na conversão
`ORDER_ID_REQUIRED`	Campo order_id obrigatório na conversão
`SHORT_LINKS_DISABLED`	Links curtos desabilitados
`SHORT_LINK_TARGET_BLOCKED_HOST`	Host da URL de destino bloqueado
`SHORT_LINK_TARGET_IMAGE_CONTENT`	URL de destino aponta para imagem, não página
`SHORT_LINK_TARGET_INVALID_URL`	URL de destino inválida
`SHORT_LINK_TARGET_NETWORK`	Falha de rede ao validar URL de destino
`SHORT_LINK_TARGET_NOT_OK_HTTP`	URL de destino retornou HTTP inválido
`SHORT_LINK_TARGET_REDIRECT`	URL de destino redireciona demais
`SHORT_LINK_TARGET_TIMEOUT`	Timeout ao validar URL de destino

Requisição geral (10)

`code`	Significado
`BAD_GATEWAY`	Bad gateway
`BAD_REQUEST`	Requisição inválida
`FORBIDDEN`	Sem permissão (escopo ou recurso)
`INTERNAL_ERROR`	Erro interno ao processar a requisição
`INVALID_CHANNEL`	Canal inválido
`METADATA_TOO_LARGE`	Campo metadata grande demais
`NOT_FOUND`	Recurso não encontrado
`NOT_IMPLEMENTED`	Recurso ainda não implementado
`SERVICE_UNAVAILABLE`	Service unavailable
`UNKNOWN_ERROR`	Unknown error

Voz (8)

`code`	Significado
`VOICE_CALL_NOT_FOUND`	Voice call not found
`VOICE_FROM_REQUIRED`	Voice from required
`VOICE_INVALID_FROM_NUMBER`	Voice invalid from number
`VOICE_RECORDING_FETCH_FAILED`	Voice recording fetch failed
`VOICE_RECORDING_NOT_FOUND`	Voice recording not found
`VOICE_RECORDING_URL_NOT_ALLOWED`	Voice recording url not allowed
`VOICE_RECORDING_URL_REDIRECT`	Voice recording url redirect
`VOICE_UNKNOWN_ACTION`	Voice unknown action

Outros (48)

`code`	Significado
`CAROUSEL_NOT_SUPPORTED_ON_META_CLOUD`	Carousel not supported on meta cloud
`CONDITION_SCHEDULE_TIME`	Condition schedule time
`CONNECT_PAGE_ERROR`	Connect page error
`CREATE_CONTACT_TASK_TITLE`	Create contact task title
`DESTINATION_NOT_AVAILABLE`	Destination not available
`ELASTICEMAIL`	Elasticemail
`FAILED`	Failed
`GUPSHUP_AUTH_ERROR`	Falha de autenticação com parceiro BSP
`GUPSHUP_METADATA_MISSING`	Metadados BSP incompletos na instância hospedada
`GUPSHUP_NETWORK_ERROR`	Falha de rede com parceiro WhatsApp (Gupshup)
`GUPSHUP_TEMPLATE_NOT_EDITABLE`	BSP bloqueou edição; status rejeitado não sincronizado
`GUPSHUP_TEMPLATE_PENDING`	Template ainda em análise na Meta (BSP)
`GUPSHUP_TOKEN_INVALID`	Gupshup token invalid
`INSTANCE_CAPACITY_FULL`	Capacidade de instâncias cheia
`INSTANCE_SUSPENDED`	Instance suspended
`INVALID_BATCH_SIZE`	Invalid batch size
`INVALID_REQUEST`	Invalid request
`INVALID_SCOPE`	Invalid scope
`INVALID_SUPPRESSION_REASON`	Invalid suppression reason
`INVALID_SUPPRESSION_TYPE`	Invalid suppression type
`INVALID_TEMPLATE_ID`	Invalid template id
`INVALID_WEBHOOK_EVENT`	Invalid webhook event
`MESSAGE_EDIT_FAILED`	Falha ao editar mensagem
`META_CALLING_SETTINGS_FAILED`	Meta calling settings failed
`META_MESSAGE_DELETE_UNSUPPORTED`	Linha oficial não apaga mensagem já enviada
`META_MESSAGE_EDIT_UNSUPPORTED`	Linha oficial não edita mensagem já enviada
`META_PERMISSION_REQUEST_FAILED`	Meta permission request failed
`META_SYNC_FAILED`	Falha ao sincronizar catálogo de templates com a Meta
`META_TEMPLATE_CREATE_FAILED`	Meta recusou criação do template
`META_TEMPLATE_DELETION_PENDING`	Meta ainda excluindo versão anterior
`META_TEMPLATE_ID_REQUIRED`	Template ainda não vinculado à Meta
`META_TEMPLATE_UPDATE_FAILED`	Meta recusou atualização (limite 24h)
`NO_INSTANCE_FOR_WABA`	Sem instância ativa para a WABA no workspace
`NO_WORKSPACE`	No workspace
`ORIGINS_NOT_CONFIGURED`	Origins not configured
`PENDING`	Pending
`PIPELINE_CARD_MOVE_TARGET`	Pipeline card move target
`SEND_WEB_WIDGET_TRIGGER`	Send web widget trigger
`SES`	Ses
`SESSION_REQUIRED`	Session required
`SUPPRESSION_NOT_FOUND`	Suppression not found
`TOO_MANY_REQUESTS`	Too many requests
`TRUST_DAILY_LIMIT`	Workspace atingiu o teto diário do Trust Factor
`UPDATE_CONTACT_TAGS_EMPTY`	Update contact tags empty
`WABA_MISSING`	WABA da instância não identificada
`WABA_REQUIRED`	Instância sem WABA vinculada (sync/publicação)
`WORKSPACE_NOT_FOUND`	Workspace not found
`WORKSPACE_OWNER_NOT_FOUND`	Workspace owner not found

Guias simples

Conheça mais

Workspaces

OAuth 2.1

IA e no-code

BYOK

Changelog

Platform API

Conta

API Keys

Billing

Créditos

Equipe

Metadados

OAuth

Webhooks

Entregas

Logs

Workspaces

O que é uma resposta de erro?

Para que serve?

Formato padrão

Códigos HTTP mais comuns

Situações especiais

Verificar domínio de e-mail (`POST /v1/email/domains/:id/verify`)

Denúncias FELCA (`POST /v1/report`)

Download de mídia WhatsApp inbound

Download de mídia Telegram inbound

Download de mídia Instagram inbound

Sending Pools (WhatsApp)

Proteção de número (WhatsApp)

Grupos (WhatsApp, não oficial)

Linha oficial Meta (WhatsApp)

Publicação e sincronização de templates (API v1)

Lista completa de enums (`code`)

Próximos passos

​O que é uma resposta de erro?

​Para que serve?

​Formato padrão

​Códigos HTTP mais comuns

​Situações especiais

​Verificar domínio de e-mail (POST /v1/email/domains/:id/verify)

​Denúncias FELCA (POST /v1/report)

​Download de mídia WhatsApp inbound

​Download de mídia Telegram inbound

​Download de mídia Instagram inbound

​Sending Pools (WhatsApp)

​Proteção de número (WhatsApp)

​Grupos (WhatsApp, não oficial)

​Linha oficial Meta (WhatsApp)

​Publicação e sincronização de templates (API v1)

​Lista completa de enums (code)

​Próximos passos

O que é uma resposta de erro?

Para que serve?

Formato padrão

Códigos HTTP mais comuns

Situações especiais

Verificar domínio de e-mail (`POST /v1/email/domains/:id/verify`)

Denúncias FELCA (`POST /v1/report`)

Download de mídia WhatsApp inbound

Download de mídia Telegram inbound

Download de mídia Instagram inbound

Sending Pools (WhatsApp)

Proteção de número (WhatsApp)

Grupos (WhatsApp, não oficial)

Linha oficial Meta (WhatsApp)

Publicação e sincronização de templates (API v1)

Lista completa de enums (`code`)

Próximos passos