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.
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_VALIDATIONe os outrosFST_ERR_*,subscription_inactive,number_limit_reached,plan_feature_required,edit_window_closedenot_on_whatsapp; - no próprio campo
error, em snake_case, com os detalhes emmessage:invalid_recipient,already_paired,not_pairing,new_recipient_cap_reached,pairing_code_too_sooneunsupported_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
}
}<?php
// Os identificadores que chegam no campo error (os outros chegam em code)
const ERROR_IDS = [
'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(array $body): ?string
{
if (isset($body['code']) && is_string($body['code'])) {
return $body['code'];
}
$error = $body['error'] ?? null;
return in_array($error, ERROR_IDS, true) ? $error : null;
}# Os identificadores que chegam no campo error (os outros chegam em code)
ERROR_IDS = {
"invalid_recipient",
"already_paired",
"not_pairing",
"new_recipient_cap_reached",
"pairing_code_too_soon",
"unsupported_by_provider",
}
def error_id_of(body: dict):
"""O identificador de um erro da API, ou None quando só o status decide."""
code = body.get("code")
if isinstance(code, str):
return code
error = body.get("error")
return error if error in ERROR_IDS else NoneResumo
| Identificador | Campo | Status | Onde aparece |
|---|---|---|---|
FST_ERR_VALIDATION | code | 400 | Qualquer operação: o corpo, o caminho ou a query não seguem o schema |
invalid_recipient | error | 400 | Enviar mensagem |
not_on_whatsapp | code | 400 | Marcar como lidas, Mostrar presença, Editar mensagem, Apagar mensagem |
subscription_inactive | code | 402 | As operações que usam a sessão do WhatsApp do número (lista abaixo) |
number_limit_reached | code | 402 | Criar conexão, Criar conexão no projeto |
plan_feature_required | code | 403 | As operações de mensagem PRO: editar, apagar, marcar como lidas e presença |
already_paired | error | 409 | Código de pareamento |
not_pairing | error | 409 | Código de pareamento |
edit_window_closed | code | 409 | Editar mensagem |
new_recipient_cap_reached | error | 429 | Enviar mensagem |
pairing_code_too_soon | error | 429 | Código de pareamento |
unsupported_by_provider | error | 501 | As 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.
| Identificador | Quando | O 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 lista | Corrija 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 WhatsApp | Confira o número. Verificar números diz quais estão no WhatsApp |
Campo missingVariables | O envio usa um template e não mandou todas as variables que ele pede | Mande as variáveis listadas em missingVariables |
FST_ERR_CTP_EMPTY_JSON_BODY (code) | A requisição tem Content-Type: application/json e corpo vazio | Numa 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álido | Gere o corpo com um serializador de JSON, nunca concatenando texto |
| Sem identificador | O 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 é aceito | Corrija a requisição. Para a conexão que não está open, pareie ou reconecte o número: veja Parear um número |
{
"statusCode": 400,
"code": "FST_ERR_VALIDATION",
"error": "Bad Request",
"message": "body must have required property 'to'"
}{
"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"
}{
"error": "Missing required variables",
"missingVariables": ["nome", "horario"]
}{
"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:
{ "error": "Unauthorized" }| Quando | O que fazer |
|---|---|
Nenhuma chave foi enviada, nem em Authorization: Bearer nem em X-Api-Key | Envie a chave em um dos dois cabeçalhos. Veja Cabeçalhos |
| A chave é desconhecida, foi revogada ou expirou | Use uma chave válida. Veja Autenticação |
| O projeto da chave foi desativado | As chaves de um projeto desativado não autenticam mais |
| Os dois cabeçalhos foram enviados com chaves diferentes | Envie 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.
| Identificador | Quando | O que fazer |
|---|---|---|
subscription_inactive (code) | O período de teste acabou, ou uma fatura venceu e passou do prazo de carência | Regularize 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ção | Exclua uma conexão ou contrate mais números no painel |
{
"error": "The organization cannot use WhatsApp now: its trial ended or an invoice is overdue. Pay to resume",
"code": "subscription_inactive"
}{
"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:
- Conexões: Criar conexão, QR code e status, Código de pareamento, Listar grupos.
- Projetos: Criar conexão no projeto, QR code como imagem, Reconectar conexão.
- Mensagens: Enviar mensagem, Reagir, Editar mensagem, Apagar mensagem, Marcar como lidas, Mostrar presença.
- Contatos: Verificar números, Perfil do contato.
403: sem permissão
A chave é válida, mas não pode fazer esta operação.
| Identificador | Quando | O que fazer |
|---|---|---|
| Sem identificador | A chave não tem o escopo da operação. A mensagem cita o escopo: This credential lacks the messages:send scope | Use 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 identificador | Ao 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 ela | Use uma chave com os escopos e a validade necessários |
| Sem identificador | Ao atualizar o projeto: o corpo muda name, planId, isActive ou um dos limites maxPer…, que só a plataforma altera | Mande só os campos de webhook do projeto. Veja Projetos e conexões |
{
"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.
| Quando | Exemplo 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 chave | Connection 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ão | Template '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 horas | Message 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 expirou | Not found |
| O caminho não existe na API, ou é uma rota que chaves de API não usam | Not 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.
| Identificador | Quando | O 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 terminando | Para 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-After | Conecte 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ção | Envie uma mensagem nova |
| Sem identificador | Criar uma chave num projeto desativado; o projeto já tem 50 chaves ativas; rotacionar uma chave já rotacionada, revogada ou expirada | Reative o projeto, revogue uma chave, ou crie uma chave nova em vez de rotacionar |
| Sem identificador | Criar um template com um nome que já existe na conexão | Use outro nome ou atualize o template |
| Sem identificador | Reenviar uma entrega de webhook que já foi entregue, ou cujo payload não foi registrado (grande demais) | Nada a reenviar |
| Sem identificador | Excluir uma conexão cujo logout do WhatsApp falhou: a conexão não foi excluída | Repita a exclusão |
{
"error": "already_paired",
"message": "The connection is linked to a number, or a link is completing: log it out first to link another"
}{
"error": "not_pairing",
"message": "The connection is not pairing with its QR code up (status: close): connect it again, then ask for a code"
}{
"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
| Status | Identificador (code) | Quando | O que fazer |
|---|---|---|---|
413 | FST_ERR_CTP_BODY_TOO_LARGE | O corpo passou de 1 MiB | Diminua o corpo. Mídia vai por URL (media.url), nunca no corpo |
415 | FST_ERR_CTP_INVALID_MEDIA_TYPE | O corpo veio com um Content-Type que a API não lê, como application/x-www-form-urlencoded ou multipart/form-data | Envie 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:
| Identificador | Limite | Como reconhecer | O 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-After | Contatos 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 hora | Retry-After | Espere Retry-After segundos: cada código gera um aviso no celular |
| Sem identificador | Requisições demais do mesmo IP: 600 por minuto, por padrão | Retry-After; corpo com statusCode: 429 e error: "Too Many Requests" | Espere Retry-After segundos e diminua o ritmo |
| Sem identificador | Falhas de autenticação demais do mesmo IP: 20 em 5 minutos, por padrão | Retry-After; error: "Too many failed authentication attempts" | Corrija a chave. A chave certa continua funcionando |
| Sem identificador | A 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 mensal | Repetir não adianta até a cota renovar ou o plano mudar |
| Sem identificador | Verificações de proxy demais da organização: 60 por hora (só em Definir proxy) | Retry-After | Espere Retry-After segundos |
{
"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"
}{
"error": "pairing_code_too_soon",
"message": "A pairing code was asked for this connection less than 30 seconds ago: each one notifies the phone"
}{
"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
{ "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
| Quando | Como reconhecer | O que fazer |
|---|---|---|
| A instância do gateway que atende a conexão está mudando (um reinício, uma troca) ou não responde | Retry-After | Espere Retry-After segundos e repita |
| Ao definir um proxy: o gateway está sem a chave de criptografia das credenciais de proxy | Sem Retry-After | Fale com o suporte |
{
"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:
reason | O que houve | O que fazer |
|---|---|---|
attempts_exhausted | Todas as tentativas de envio falharam | Confira a conexão e reenvie com um clientRef novo |
lease_expired | O envio travou na última tentativa (por exemplo, num reinício); ele pode ter saído mesmo assim | Espere um message.outgoing ou um message.delivery do mesmo clientRef antes de reenviar |
not_on_whatsapp | O número não está no WhatsApp; não há novas tentativas | Corrija o número |
reachout_timelocked | A conta está num bloqueio temporário do WhatsApp para iniciar conversas; o envio foi recusado sem ser tentado | Reenvie 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-Percente 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.