Erros e limites

Formato de erro

Toda resposta de erro é um objeto plano — não há um sub-objeto details, os campos extras vêm soltos no mesmo nível de error e code:

{
  "error": "ERR_TOKEN_INVALID",
  "code": "ERR_TOKEN_INVALID"
}

Alguns erros trazem campos extras direto no corpo, conforme o caso:

{ "error": "Limite de requisições excedido", "code": "ERR_RATE_LIMITED", "retryAfter": 4 }

{ "error": "Token válido, mas sem o escopo exigido", "code": "ERR_SCOPE_MISSING", "requiredScope": "contacts:write" }

{ "error": "ERR_TICKET_IN_HUMAN_SERVICE", "code": "ERR_TICKET_IN_HUMAN_SERVICE", "ticketId": 933 }

{ "error": "ERR_INVALID_DATE_FILTER", "code": "ERR_INVALID_DATE_FILTER", "param": "createdAtAfter" }

error — texto pra exibição/log. Pode mudar de uma versão pra outra. Para cerca de 22 códigos ele repete o próprio code (como ERR_TOKEN_INVALID acima); para os demais é um texto legível em português (como ERR_RATE_LIMITED acima). Não dá pra prever qual caso é qual sem consultar o catálogo — por isso a regra abaixo.
code — identificador estável, sempre em maiúsculas com prefixo ERR_.
retryAfter, requiredScope, ticketId, param — extras que aparecem só em alguns códigos específicos (429, 403, 409 de flows, ERR_INVALID_DATE_FILTER).

Não faça match em error — nem para saber o tipo do erro, nem por igualdade de texto. Use sempre code: é o único campo estável entre versões.

Catálogo de códigos

Código	HTTP	Quando acontece
`ERR_TOKEN_MISSING`	401	Header `Authorization` ausente. Envie `Authorization: Bearer wtx_live_…`.
`ERR_TOKEN_INVALID`	401	O token não existe ou está mal formado. Gere um novo na tela API, aba Tokens.
`ERR_TOKEN_REVOKED`	401	O token foi revogado no painel. Crie outro.
`ERR_TOKEN_EXPIRED`	401	Passou da validade definida na criação. Crie outro ou rotacione antes de expirar.
`ERR_SCOPE_MISSING`	403	O token é válido mas não tem o escopo exigido pelo endpoint. Um escopo `x:write` satisfaz `x:read`.
`ERR_RATE_LIMITED`	429	Mais de 120 requisições por minuto com o mesmo token. Aguarde os segundos de `Retry-After`.
`ERR_MISSING_CONTENT`	400	O envio precisa de pelo menos um entre `body`, `medias` (multipart) ou `templateData`.
`ERR_NUMBER_REQUIRED`	400	O campo `number` é obrigatório.
`ERR_NUMBER_INVALID`	400	O número não tem dígitos válidos após normalização. Use E.164 sem `+` (ex.: 5534999990000).
`ERR_CONNECTION_NOT_FOUND`	404	`whatsappId`/`whatsappName` não corresponde a uma conexão desta conta.
`ERR_NO_CONNECTION_AVAILABLE`	404	A conta não tem nenhuma conexão `whatsapp`/`waba`. Informe `whatsappId`/`whatsappName` ou conecte um canal no painel.
`ERR_UNSUPPORTED_CHANNEL`	400 no envio (`POST /v1/messages/send`), 422 no disparo de flow (`POST /v1/flows/trigger`)	A conexão escolhida não é `whatsapp`/`waba` — só esses dois canais enviam pela API.
`ERR_NO_TICKET_FOUND`	404	Conversa (ticket) inexistente ou de outra conta.
`ERR_MESSAGE_NOT_FOUND`	404	Mensagem inexistente ou de outra conta.
`ERR_MISSING_NUMBER`	400	`number` é obrigatório no upsert de contato.
`ERR_NUMBER_NOT_ON_WHATSAPP`	422	Com `validateNumber=true`, o número não existe no WhatsApp.
`ERR_WHATSAPP_NOT_FOUND`	404	`whatsappId` informado não é uma conexão desta conta.
`ERR_NO_CONTACT_FOUND`	404	Contato inexistente ou de outra conta.
`ERR_NUMBER_IMMUTABLE`	400	`PUT /v1/contacts/{contactId}` não aceita `number`. Corrija o número pelo painel.
`ERR_INVALID_TAG_IDS`	400	`tagIds` ausente, não é array, ou contém tag de outra conta.
`ERR_INVALID_DATE_FILTER`	400	Filtro de data sem offset de fuso (use `2026-09-01T00:00:00-03:00`). Vem com `param` indicando qual parâmetro falhou.
`ERR_NO_CARD_FOUND`	404	Card inexistente ou de outra conta.
`ERR_CONTACT_IDENTIFIER_REQUIRED`	400	Informe exatamente um entre `contactId` e `phone` ao criar card.
`ERR_PIPELINE_NOT_FOUND`	404	`pipelineId` inexistente ou de outra conta.
`ERR_STAGE_REQUIRED`	400	`stageId` é obrigatório ao mover card.
`ERR_STAGE_NOT_FOUND`	404	`stageId` inexistente ou de outra conta.
`ERR_STAGE_NOT_IN_PIPELINE`	422	A etapa existe, mas pertence a outro pipeline. Mover entre pipelines não é permitido.
`ERR_SOURCE_NOT_FOUND`	404	`sourceId` (origem do card) inexistente ou de outra conta.
`ERR_FLOW_ID_AND_WHATSAPP_ID_REQUIRED`	400	`flowId` e `whatsappId` são obrigatórios.
`ERR_VARIABLES_MUST_BE_OBJECT`	400	`variables` precisa ser um objeto JSON (chave → valor).
`ERR_FLOW_NOT_FOUND`	404	Flow inexistente ou de outra conta.
`ERR_FLOW_NOT_EXECUTABLE`	422	Flow inativo, despublicado ou sem nós. Publique-o no FlowBuilder.
`ERR_TICKET_IN_HUMAN_SERVICE`	409	O contato está em atendimento humano ativo; o flow não é disparado pra não atropelar o atendente.

Rate limit

Cada token pode fazer até 120 requisições por minuto. Toda resposta — inclusive as de erro — traz os headers:

X-RateLimit-Limit — limite por minuto (120).
X-RateLimit-Remaining — quantas ainda restam na janela atual.
X-RateLimit-Reset — epoch (segundos) de quando a janela reseta.

Ao exceder, a API responde 429 com code: ERR_RATE_LIMITED e o header Retry-After (segundos até poder tentar de novo).

Backoff em Node

async function callApi(url, options, attempt = 1) {
  const r = await fetch(url, options);
  if (r.status === 429 && attempt < 3) {
    const retryAfter = Number(r.headers.get("Retry-After") ?? "1");
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return callApi(url, options, attempt + 1);
  }
  return r;
}

Limite as tentativas (aqui, 3) em vez de retentar indefinidamente — se o 429 persistir depois disso, o problema provavelmente não é uma rajada passageira, e vale investigar o padrão de chamadas da sua integração antes de continuar insistindo.

Se sua integração faz muitas chamadas em rajada, prefira paginar com calma ou distribuir as chamadas no tempo em vez de confiar só no retry — o limite é por token, então rajadas grandes derrubam o Remaining rápido.

Início

Guias

Referência

Erros e limites

Formato de erro

Catálogo de códigos

Rate limit

Backoff em Node

​Formato de erro

​Catálogo de códigos

​Rate limit

​Backoff em Node

Formato de erro

Catálogo de códigos

Rate limit

Backoff em Node