Pular para o conteúdo

Códigos de erro

Cada identificador de erro da API, por status HTTP: onde aparece, o corpo que chega e o que fazer. Mais os motivos de falha que chegam pelos webhooks.

Ver em Markdown

Todo erro da API responde um status HTTP e um corpo JSON com pelo menos o campo error. Alguns erros trazem também um identificador estável, que o seu código pode comparar sem depender do texto. Ele fica em um de dois lugares:

  • no campo code: FST_ERR_VALIDATION e os outros FST_ERR_*, subscription_inactive, number_limit_reached, plan_feature_required, edit_window_closed e not_on_whatsapp;
  • no próprio campo error, em snake_case, com os detalhes em message: invalid_recipient, already_paired, not_pairing, new_recipient_cap_reached, pairing_code_too_soon e unsupported_by_provider.

Os demais erros não têm identificador: decida pelo status HTTP. O texto de error e de message é para pessoas e pode mudar; nunca compare frases. Como tratar cada status, com exemplos de repetição, está no guia Erros.

// Os identificadores que chegam no campo error (os outros chegam em code)
const ERROR_IDS = new Set([
  'invalid_recipient',
  'already_paired',
  'not_pairing',
  'new_recipient_cap_reached',
  'pairing_code_too_soon',
  'unsupported_by_provider',
])

// O identificador de um erro da API, ou null quando só o status decide
function errorIdOf(body) {
  if (typeof body?.code === 'string') return body.code
  return ERROR_IDS.has(body?.error) ? body.error : null
}

const res = await fetch(`https://api.apiwpp.com/connections/${process.env.CONNECTION_ID}/send`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: '5511988887777', message: 'Olá!', clientRef: 'pedido-1234' }),
})

if (!res.ok) {
  const body = await res.json().catch(() => ({}))
  switch (errorIdOf(body)) {
    case 'invalid_recipient':
      // corrija o destinatário; repetir não adianta
      break
    case 'new_recipient_cap_reached':
      // só contatos novos: espere Retry-After segundos
      break
    case 'subscription_inactive':
      // avise quem cuida da assinatura
      break
    default:
      // decida pelo status: res.status
  }
}

Resumo

IdentificadorCampoStatusOnde aparece
FST_ERR_VALIDATIONcode400Qualquer operação: o corpo, o caminho ou a query não seguem o schema
invalid_recipienterror400Enviar mensagem
not_on_whatsappcode400Marcar como lidas, Mostrar presença, Editar mensagem, Apagar mensagem
subscription_inactivecode402As operações que usam a sessão do WhatsApp do número (lista abaixo)
number_limit_reachedcode402Criar conexão, Criar conexão no projeto
plan_feature_requiredcode403As operações de mensagem PRO: editar, apagar, marcar como lidas e presença
already_pairederror409Código de pareamento
not_pairingerror409Código de pareamento
edit_window_closedcode409Editar mensagem
new_recipient_cap_reachederror429Enviar mensagem
pairing_code_too_soonerror429Código de pareamento
unsupported_by_providererror501As operações que o provedor da conexão não oferece (lista abaixo)

Um envio com template que não recebeu todas as variáveis responde 400 sem identificador, mas com o campo missingVariables: veja 400.

400: requisição inválida

A requisição não pode ser atendida como veio. Repetir sem mudar nada dá o mesmo erro.

IdentificadorQuandoO que fazer
FST_ERR_VALIDATION (code)O corpo, o caminho ou a query não seguem o schema da operação: um campo obrigatório faltando, um tipo errado, um valor fora da listaCorrija a requisição conforme a página da operação. message diz qual campo
invalid_recipient (error)O to de um envio não é um telefone com DDI nem o JID de uma pessoa (@s.whatsapp.net, @lid), de um grupo (@g.us), de uma lista de transmissão ou de um canal (newsletter)Corrija o destinatário. Veja Enviar mensagens
not_on_whatsapp (code)Nas operações de mensagem PRO, a conversa to não está no WhatsAppConfira o número. Verificar números diz quais estão no WhatsApp
Campo missingVariablesO envio usa um template e não mandou todas as variables que ele pedeMande as variáveis listadas em missingVariables
FST_ERR_CTP_EMPTY_JSON_BODY (code)A requisição tem Content-Type: application/json e corpo vazioNuma operação sem corpo, não mande Content-Type; nas outras, mande o JSON
FST_ERR_CTP_INVALID_JSON_BODY (code)O corpo não é um JSON válidoGere o corpo com um serializador de JSON, nunca concatenando texto
Sem identificadorO envio não tem conteúdo (é preciso um de message, media, location ou template); media com type inválido, sem url ou, em document, sem mimetype; a conexão não está open (Connection not ready (status: …)); o phone do código de pareamento não é um número com DDI de 8 a 15 dígitos; o proxy informado é inválido; o expiresAt de uma chave nova está no passado; o webhookBaseUrl não é aceitoCorrija a requisição. Para a conexão que não está open, pareie ou reconecte o número: veja Parear um número
400
{
  "statusCode": 400,
  "code": "FST_ERR_VALIDATION",
  "error": "Bad Request",
  "message": "body must have required property 'to'"
}
400
{
  "error": "invalid_recipient",
  "message": "to must be a phone number (country code first) or the JID of a person (@s.whatsapp.net, @lid), a group (@g.us), a broadcast list or a newsletter"
}
400
{
  "error": "Missing required variables",
  "missingVariables": ["nome", "horario"]
}
400
{
  "error": "The chat is not on WhatsApp",
  "code": "not_on_whatsapp"
}

401: sem autenticação

A requisição não tem uma chave de API válida. O corpo é sempre o mesmo, sem identificador:

401
{ "error": "Unauthorized" }
QuandoO que fazer
Nenhuma chave foi enviada, nem em Authorization: Bearer nem em X-Api-KeyEnvie a chave em um dos dois cabeçalhos. Veja Cabeçalhos
A chave é desconhecida, foi revogada ou expirouUse uma chave válida. Veja Autenticação
O projeto da chave foi desativadoAs chaves de um projeto desativado não autenticam mais
Os dois cabeçalhos foram enviados com chaves diferentesEnvie a chave em um só cabeçalho, ou a mesma nos dois

Não repita com a mesma chave: cada chave errada conta para o limite de falhas de autenticação, que responde 429 depois de 20 falhas em 5 minutos a partir do mesmo IP.

402: pagamento necessário

A organização dona da conexão ou do projeto não pode fazer a operação por causa da assinatura ou do plano contratado.

IdentificadorQuandoO que fazer
subscription_inactive (code)O período de teste acabou, ou uma fatura venceu e passou do prazo de carênciaRegularize a assinatura no painel. Desconectar, sair do WhatsApp, excluir a conexão e consultar a fila continuam permitidos
number_limit_reached (code)A nova conexão passaria do número de números contratados pela organizaçãoExclua uma conexão ou contrate mais números no painel
402
{
  "error": "The organization cannot use WhatsApp now: its trial ended or an invoice is overdue. Pay to resume",
  "code": "subscription_inactive"
}
402
{
  "error": "The organization holds its 3 number(s): delete one or contract more",
  "code": "number_limit_reached"
}

subscription_inactive pode aparecer nas operações que usam a sessão do WhatsApp do número:

403: sem permissão

A chave é válida, mas não pode fazer esta operação.

IdentificadorQuandoO que fazer
Sem identificadorA chave não tem o escopo da operação. A mensagem cita o escopo: This credential lacks the messages:send scopeUse uma chave com o escopo. Veja Escopos
plan_feature_required (code)O plano da organização não inclui o recurso da operação. O campo feature diz qual: nas operações públicas, é sempre message_ops (editar, apagar, marcar como lidas e presença, que são PRO)Mude para um plano com o recurso no painel
Sem identificadorAo criar, rotacionar ou revogar uma chave: a chave chamadora tenta dar escopos que ela não tem, ou criar uma chave que dura mais do que elaUse uma chave com os escopos e a validade necessários
Sem identificadorAo atualizar o projeto: o corpo muda name, planId, isActive ou um dos limites maxPer…, que só a plataforma alteraMande só os campos de webhook do projeto. Veja Projetos e conexões
403
{
  "error": "The organization's plan does not include message_ops",
  "code": "plan_feature_required",
  "feature": "message_ops"
}

Numa operação com as duas travas, a de assinatura vem primeiro: uma organização com a assinatura inativa recebe 402 subscription_inactive, e não 403 plan_feature_required.

404: não encontrado

O recurso não existe ou pertence a outra pessoa. As duas respostas são idênticas, de propósito: a API nunca revela se um id de outra organização existe. Sem identificador.

QuandoExemplo de error
A conexão, o projeto, a chave, o template ou a entrega não existem, ou não são do projeto da chaveConnection not found, Tenant not found, API key not found, Template not found, Delivery not found, Not found
O template de um envio não existe na conexãoTemplate 'lembrete' not found
Editar ou apagar uma mensagem que a conexão não enviou pela API, ou que foi enviada há mais de 72 horasMessage not found: this connection did not send it through the API, or not in the last 72 hours
A URL de uma mídia é inválida ou expirouNot found
O caminho não existe na API, ou é uma rota que chaves de API não usamNot found

Confira os ids e se a chave é do projeto certo: GET /me diz de qual projeto é a chave.

409: conflito

A operação conflita com o estado atual do recurso. Leia o estado antes de repetir.

IdentificadorQuandoO que fazer
already_paired (error)Pedir um código de pareamento para uma conexão já ligada a um número, ou com uma ligação terminandoPara ligar outro número, saia do WhatsApp antes
not_pairing (error)Pedir um código de pareamento para uma conexão que não está pareando com um QR code no ar. Quando os QR codes do pareamento terminam cedo demais para alguém digitar um código, a resposta traz Retry-AfterConecte de novo e peça o código. Com Retry-After, espere esse número de segundos e peça de novo
edit_window_closed (code)Editar uma mensagem enviada há mais de 15 minutos: o WhatsApp não aplica mais a ediçãoEnvie uma mensagem nova
Sem identificadorCriar uma chave num projeto desativado; o projeto já tem 50 chaves ativas; rotacionar uma chave já rotacionada, revogada ou expiradaReative o projeto, revogue uma chave, ou crie uma chave nova em vez de rotacionar
Sem identificadorCriar um template com um nome que já existe na conexãoUse outro nome ou atualize o template
Sem identificadorReenviar uma entrega de webhook que já foi entregue, ou cujo payload não foi registrado (grande demais)Nada a reenviar
Sem identificadorExcluir uma conexão cujo logout do WhatsApp falhou: a conexão não foi excluídaRepita a exclusão
409
{
  "error": "already_paired",
  "message": "The connection is linked to a number, or a link is completing: log it out first to link another"
}
409
{
  "error": "not_pairing",
  "message": "The connection is not pairing with its QR code up (status: close): connect it again, then ask for a code"
}
409
{
  "error": "The message was sent more than 15 minutes ago: WhatsApp no longer applies an edit",
  "code": "edit_window_closed"
}

413 e 415: corpo da requisição

StatusIdentificador (code)QuandoO que fazer
413FST_ERR_CTP_BODY_TOO_LARGEO corpo passou de 1 MiBDiminua o corpo. Mídia vai por URL (media.url), nunca no corpo
415FST_ERR_CTP_INVALID_MEDIA_TYPEO corpo veio com um Content-Type que a API não lê, como application/x-www-form-urlencoded ou multipart/form-dataEnvie o corpo em JSON, com Content-Type: application/json

Esses erros têm o mesmo formato da validação do schema: statusCode, code, error e message. Um corpo enviado como text/plain não recebe 415: ele chega como texto e falha na validação do schema, com 400 FST_ERR_VALIDATION.

422: proxy recusado

O proxy informado ao criar uma conexão ou em Definir proxy não passou na verificação: o gateway não conseguiu sair por ele. Sem identificador; error diz o que falhou. Confira o endereço, a porta e as credenciais do proxy. Veja Proxy e IP dedicado.

429: limite atingido

O mesmo status cobre limites diferentes. O identificador, quando existe, e os cabeçalhos dizem qual foi:

IdentificadorLimiteComo reconhecerO que fazer
new_recipient_cap_reached (error)O número já alcançou o limite de destinatários novos das últimas 24 horas (100, por padrão)Retry-AfterContatos conhecidos continuam sendo aceitos. Para os novos, espere Retry-After segundos
pairing_code_too_soon (error)Um código de pareamento foi pedido para a conexão há menos de 30 segundos, ou o número já recebeu 5 códigos na última horaRetry-AfterEspere Retry-After segundos: cada código gera um aviso no celular
Sem identificadorRequisições demais do mesmo IP: 600 por minuto, por padrãoRetry-After; corpo com statusCode: 429 e error: "Too Many Requests"Espere Retry-After segundos e diminua o ritmo
Sem identificadorFalhas de autenticação demais do mesmo IP: 20 em 5 minutos, por padrãoRetry-After; error: "Too many failed authentication attempts"Corrija a chave. A chave certa continua funcionando
Sem identificadorA cota diária ou mensal de mensagens da organização (só no envio)X-Usage-Percent, sem Retry-After; error diz se foi o limite diário ou o mensalRepetir não adianta até a cota renovar ou o plano mudar
Sem identificadorVerificações de proxy demais da organização: 60 por hora (só em Definir proxy)Retry-AfterEspere Retry-After segundos
429
{
  "error": "new_recipient_cap_reached",
  "message": "This number already reached 100 new recipients (people it exchanged no message with in the last 28 days since its current link; a re-pair makes every contact new) in the last 24 hours; reaching out to more gets it restricted by WhatsApp. Retry after Retry-After seconds"
}
429
{
  "error": "pairing_code_too_soon",
  "message": "A pairing code was asked for this connection less than 30 seconds ago: each one notifies the phone"
}
429
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded, retry in 1 minute"
}

Os números são os padrões do gateway. O ritmo de envio por número (mensagens por minuto, hora e dia) não gera 429: ele só espaça a fila. Veja Limites de envio e Limites.

500: falha do gateway

Uma falha inesperada do gateway, ou de uma chamada ao WhatsApp que não deu certo (por exemplo, Failed to request a pairing code ou Failed to edit the message). Sem identificador. Repita com espera crescente (1 s, 2 s, 4 s…) e um número máximo de tentativas; nos envios, sempre com o mesmo clientRef.

501: operação não suportada

501
{ "error": "unsupported_by_provider" }

O provedor da conexão não oferece a operação. Repetir não muda nada: use outra operação ou outra conexão. Pode aparecer em Criar conexão, Criar conexão no projeto, Código de pareamento, Listar grupos, Definir proxy, Verificar números, Perfil do contato, Reagir e nas operações de mensagem PRO.

503: indisponível no momento

QuandoComo reconhecerO que fazer
A instância do gateway que atende a conexão está mudando (um reinício, uma troca) ou não respondeRetry-AfterEspere Retry-After segundos e repita
Ao definir um proxy: o gateway está sem a chave de criptografia das credenciais de proxySem Retry-AfterFale com o suporte
503
{
  "error": "The connection cannot be reached right now: the gateway instance that runs it is changing or does not answer; try again in a few seconds"
}

Motivos de falha nos webhooks

Um envio aceito (202) que não acontece não volta como erro HTTP. Ele chega depois, pelos webhooks, com um motivo em reason.

message.send_failed, só para envios feitos com clientRef:

reasonO que houveO que fazer
attempts_exhaustedTodas as tentativas de envio falharamConfira a conexão e reenvie com um clientRef novo
lease_expiredO envio travou na última tentativa (por exemplo, num reinício); ele pode ter saído mesmo assimEspere um message.outgoing ou um message.delivery do mesmo clientRef antes de reenviar
not_on_whatsappO número não está no WhatsApp; não há novas tentativasCorrija o número
reachout_timelockedA conta está num bloqueio temporário do WhatsApp para iniciar conversas; o envio foi recusado sem ser tentadoReenvie depois do fim do bloqueio, com um clientRef novo

message.delivery com status: "failed" pode trazer reason: "reachout_timelocked": o WhatsApp recusou a mensagem como uma abordagem nova (em geral, a um contato com quem o número nunca conversou). Ela não foi entregue e não será tentada de novo. Reenviar agrava a restrição: acompanhe o reason reachout_timelock do evento connection.status.

Próximos passos

  • Erros: o corpo de erro, cada status e como repetir com segurança.
  • Cabeçalhos: Retry-After, X-Usage-Percent e os outros cabeçalhos das respostas.
  • Escopos: o escopo de cada operação, para evitar o 403.
  • Limites: todos os números por trás dos 429.
Esta página ajudou? · Atualizado em 29 set 2026