Erros

Formato padrão

Todas as respostas de erro seguem o mesmo formato:

{
  "error": "Descrição do erro",
  "code": "CODIGO_MAQUINA",
  "hint": "Como corrigir (quando disponível)"
}

O campo code é estável e legível por máquina — programe suas checagens contra ele, não contra o texto de error (que pode mudar e varia de idioma entre endpoints). O hint aparece só em alguns erros.

Códigos HTTP

Código	Significado
`400 Bad Request`	Corpo da requisição inválido ou campo obrigatório ausente
`401 Unauthorized`	API Key ausente, inválida ou expirada
`402 Payment Required`	Limite do plano atingido ou recurso não disponível no plano atual
`403 Forbidden`	API Key sem o escopo necessário, ou contato em opt-out
`404 Not Found`	Recurso inexistente ou de outro workspace
`409 Conflict`	Estado conflitante (ex.: requisição idempotente em andamento)
`422 Unprocessable Entity`	Requisição válida mas não pode ser executada (ex.: workspace sem WhatsApp)
`429 Too Many Requests`	Rate limit excedido
`500 Internal Server Error`	Erro interno do servidor
`502 Bad Gateway`	Falha do provedor externo (ex.: WhatsApp) ao processar o envio

Erros comuns

400 — phone is required

{ "error": "phone is required" }

O campo phone é obrigatório em todas as requisições.

400 — Invalid phone number

{ "error": "Invalid phone number — minimum 10 digits" }

O número de telefone deve ter pelo menos 10 dígitos. Aceita formato E.164 ou DDD+número brasileiro.

401 — API key expired

{
  "error": "API key expired",
  "expiredAt": "2025-04-01T00:00:00.000Z"
}

A chave atingiu a data de expiração configurada. Gere uma nova chave.

402 — Limite do plano atingido

Quando um limite do plano é atingido, a resposta é 402 com um code específico do recurso. Os registros já existentes continuam acessíveis — só a criação de novos é bloqueada.

{
  "error": "Contact limit reached for this workspace's plan",
  "code": "CONTACT_LIMIT_REACHED"
}

`code`	Recurso	Onde ocorre
`CONTACT_LIMIT_REACHED`	Contatos	`POST /api/v1/leads` ao criar um contato novo
`DEAL_LIMIT_REACHED`	Negócios	`POST /api/v1/deals` e `POST /api/v1/leads` quando o payload abre um card
`LIST_LIMIT_REACHED`	Listas de contatos	`POST /api/v1/lists`
`STORAGE_LIMIT_REACHED`	Storage de mídia	Upload de anexos — o `error` traz o consumo atual e o teto em GB

Consulte os tetos de cada plano em Planos e Limites.

402 — API access not available

{
  "error": "Acesso a API não disponível no plano atual. Faça upgrade para Crescimento ou Sob consulta.",
  "code": "API_ACCESS_REQUIRED"
}

O acesso à API está disponível em todos os planos pagos (Essencial, Crescimento e Sob consulta). Este erro só ocorre para workspaces sem plano ativo — por exemplo, no plano gratuito ou com o período de teste expirado.

402 — Subscription inactive

{ "error": "Subscription inactive", "code": "SUBSCRIPTION_INACTIVE" }

A assinatura do workspace está inativa (cancelada, suspensa, inadimplente ou trial expirado). Alguns endpoints devolvem esse mesmo code com a mensagem em português — por isso, cheque sempre o code.

422 — No WhatsApp instance

{ "error": "Workspace has no WhatsApp instance configured" }

Para criar leads via API, o workspace precisa ter pelo menos uma instância de WhatsApp conectada.

Erros dos endpoints de mensagem

Códigos específicos de POST /messages (número novo) e POST /conversations/{id}/messages (conversa existente).

400 — INVALID_PHONE

{
  "error": "Invalid phone number — informe o número no formato internacional com 55 + DDD, ex: 5511987654321",
  "code": "INVALID_PHONE"
}

O phone precisa vir no formato internacional brasileiro completo: 55 + DDD + número. Sem o 55/DDD ou com número ambíguo, o CRM recusa para não criar contato duplicado. Aceita o celular com ou sem o 9º dígito.

422 — INSTANCE_REQUIRED

{ "error": "Multiple instances — pass instanceId to choose one", "code": "INSTANCE_REQUIRED" }

O workspace tem mais de uma conexão WhatsApp. Informe instanceId no corpo. Liste as conexões em GET /instances.

404 — INSTANCE_NOT_FOUND

{ "error": "Instância não encontrada neste workspace", "code": "INSTANCE_NOT_FOUND" }

O instanceId informado não existe (ou não pertence a este workspace).

422 — NO_INSTANCE

{ "error": "Workspace has no WhatsApp instance configured", "code": "NO_INSTANCE" }

O workspace não tem nenhuma conexão WhatsApp configurada. Conecte uma instância antes de enviar.

403 — OPTED_OUT

{ "error": "Contact opted out of marketing", "code": "OPTED_OUT" }

O contato solicitou opt-out de marketing e não pode receber mensagens ativas. Não é seguro para retry.

429 — COLD_LIMIT_REACHED

{ "error": "Daily cold-start limit reached for this workspace", "code": "COLD_LIMIT_REACHED" }

O cap diário de números novos do workspace foi atingido. Reinicia no dia seguinte — veja Rate Limits.

409 — IN_PROGRESS

{ "error": "A request with this Idempotency-Key is already in progress", "code": "IN_PROGRESS" }

Já existe uma requisição em andamento com o mesmo Idempotency-Key. Aguarde a primeira concluir — quando ela termina, uma nova chamada com a mesma chave devolve a resposta memoizada (200) em vez de reenviar.

422 / 503 — TEMPLATE_HEADER_MEDIA_UNAVAILABLE

{ "error": "A mídia aprovada do cabeçalho do template não pôde ser usada.", "code": "TEMPLATE_HEADER_MEDIA_UNAVAILABLE" }

O template tem cabeçalho de mídia e ele não pode sair. A API não recebe arquivo para o cabeçalho: com cabeçalho IMAGE, o CRM usa a imagem aprovada na Meta automaticamente.

422 — definitivo: a imagem aprovada não pode ser usada (removida, formato diferente, recusada pela Meta) ou o cabeçalho é VIDEO/DOCUMENT, que a API não envia. Não repita sem mudar o template.
503 — temporário: a Meta ou a CDN dela não entregou a imagem agora. Repita com backoff.

Nos dois casos nada é enviado à Meta e a cota diária não é consumida.

422 — OFFICIAL_TOKEN_UNAVAILABLE

{ "error": "A conexão da API Oficial não tem acesso ao template ou à mídia do cabeçalho.", "code": "OFFICIAL_TOKEN_UNAVAILABLE" }

A conexão da API Oficial não conseguiu acessar o template ou a mídia do cabeçalho na Meta: token expirado ou sem permissão, ou a conta WhatsApp Business (WABA) da conexão não pôde ser identificada. Reconecte o número no CRM. Nada é enviado e a cota não é consumida.

Retry seguro

Os seguintes erros são seguros para retry:

429 Too Many Requests — aguarde o Retry-After antes de tentar novamente
409 IN_PROGRESS — aguarde e repita com o mesmo Idempotency-Key (nunca reenvia em dobro)
500 Internal Server Error / 502 SEND_FAILED — use backoff exponencial (1s, 2s, 4s…)
503 TEMPLATE_HEADER_MEDIA_UNAVAILABLE — mídia do cabeçalho indisponível no momento; backoff exponencial

Os seguintes erros não devem ser retentados sem corrigir o problema:

400 — corrija o payload
401, 402, 403 — corrija a autenticação, o plano ou o opt-out do contato
422 — verifique a configuração do workspace, a instância ou a janela de 24h

Introdução

Fundamentos da API

Formato padrão

Códigos HTTP

Erros comuns

400 — phone is required

400 — Invalid phone number

401 — API key expired

402 — Limite do plano atingido

402 — API access not available

402 — Subscription inactive

422 — No WhatsApp instance

Erros dos endpoints de mensagem

400 — INVALID_PHONE

422 — INSTANCE_REQUIRED

404 — INSTANCE_NOT_FOUND

422 — NO_INSTANCE

403 — OPTED_OUT

429 — COLD_LIMIT_REACHED

409 — IN_PROGRESS

422 / 503 — TEMPLATE_HEADER_MEDIA_UNAVAILABLE

422 — OFFICIAL_TOKEN_UNAVAILABLE

Retry seguro

​Formato padrão

​Códigos HTTP

​Erros comuns

​400 — phone is required

​400 — Invalid phone number

​401 — API key expired

​402 — Limite do plano atingido

​402 — API access not available

​402 — Subscription inactive

​422 — No WhatsApp instance

​Erros dos endpoints de mensagem

​400 — INVALID_PHONE

​422 — INSTANCE_REQUIRED

​404 — INSTANCE_NOT_FOUND

​422 — NO_INSTANCE

​403 — OPTED_OUT

​429 — COLD_LIMIT_REACHED

​409 — IN_PROGRESS

​422 / 503 — TEMPLATE_HEADER_MEDIA_UNAVAILABLE

​422 — OFFICIAL_TOKEN_UNAVAILABLE

​Retry seguro

Formato padrão

Códigos HTTP

Erros comuns

400 — phone is required

400 — Invalid phone number

401 — API key expired

402 — Limite do plano atingido

402 — API access not available

402 — Subscription inactive

422 — No WhatsApp instance

Erros dos endpoints de mensagem

400 — INVALID_PHONE

422 — INSTANCE_REQUIRED

404 — INSTANCE_NOT_FOUND

422 — NO_INSTANCE

403 — OPTED_OUT

429 — COLD_LIMIT_REACHED

409 — IN_PROGRESS

422 / 503 — TEMPLATE_HEADER_MEDIA_UNAVAILABLE

422 — OFFICIAL_TOKEN_UNAVAILABLE

Retry seguro