Erros
O corpo de erro da API, o que cada status HTTP significa, qual limite gerou um 429 e como repetir uma requisição sem duplicar nada.
Todo erro responde um status HTTP e um corpo JSON com pelo menos o campo error:
{ "error": "Connection not ready (status: close)" }Alguns erros trazem mais campos:
| Campo | Quando aparece |
|---|---|
error | Sempre. Um texto para pessoas ou, em alguns casos, um identificador estável em snake_case (veja abaixo) |
message | Os detalhes, nos erros de validação, de limite e de pareamento |
statusCode | Repete o status HTTP nos erros de validação do schema e no limite de requisições |
code | Um identificador estável: FST_ERR_VALIDATION, subscription_inactive, number_limit_reached, plan_feature_required, edit_window_closed, not_on_whatsapp |
feature | Com plan_feature_required: o recurso que o plano da organização não tem |
missingVariables | Num envio com template: as variáveis que faltaram |
{
"statusCode": 400,
"code": "FST_ERR_VALIDATION",
"error": "Bad Request",
"message": "body must have required property 'to'"
}Os identificadores
Dois lugares guardam um identificador que o seu código pode comparar. Leia code primeiro e, se ele não vier, veja se error é um dos identificadores desta tabela. A lista completa, com o que fazer em cada caso, está em Códigos de erro.
| Onde | Identificador | Status | Operação |
|---|---|---|---|
code | FST_ERR_VALIDATION | 400 | Qualquer uma: o corpo, o caminho ou a query não seguem o schema |
code | not_on_whatsapp | 400 | Editar mensagem, Apagar mensagem, Marcar como lidas e Mostrar presença |
code | subscription_inactive | 402 | As operações que usam a sessão do WhatsApp do número |
code | number_limit_reached | 402 | Criar conexão e Criar conexão no projeto |
code | plan_feature_required | 403 | As operações PRO de mensagem (editar, apagar, marcar como lidas, presença) |
code | edit_window_closed | 409 | Editar mensagem |
error | invalid_recipient | 400 | Enviar mensagem |
error | already_paired, not_pairing | 409 | Código de pareamento |
error | new_recipient_cap_reached | 429 | Enviar mensagem |
error | pairing_code_too_soon | 429 | Código de pareamento |
error | unsupported_by_provider | 501 | As operações que o provedor da conexão não oferece |
Os status
| Status | Quando | O que fazer |
|---|---|---|
400 | A requisição não segue o schema (code: FST_ERR_VALIDATION); o envio não tem conteúdo (é preciso um de message, media, location ou template); faltam variáveis do template (missingVariables); o destinatário não é um telefone nem um JID válido (error: invalid_recipient); a conversa não está no WhatsApp (code: not_on_whatsapp); ou a conexão não está open (Connection not ready (status: …)) | Corrija a requisição. Para a conexão, pareie ou reconecte o número |
401 | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é sempre { "error": "Unauthorized" } | Confira a chave. Não repita: chaves erradas repetidas levam ao 429 de falhas de autenticação |
402 | A organização não pode usar o WhatsApp agora: o período de teste acabou ou uma fatura venceu e passou da carência (code: subscription_inactive). Ou a conexão passaria dos números contratados (code: number_limit_reached) | Regularize a assinatura ou libere um número no painel. Desconectar, sair e excluir continuam permitidos |
403 | A chave não tem o escopo da operação (a mensagem cita o escopo: This credential lacks the messages:send scope); o plano não inclui o recurso (code: plan_feature_required, com feature); a chave tenta dar, rotacionar ou revogar escopos que ela não tem, ou criar uma chave que dura mais que ela | Use uma chave com o escopo, ou um plano com o recurso. Veja Escopos |
404 | O recurso não existe ou pertence a outra pessoa: as duas respostas são idênticas. Também a mensagem que não foi enviada pela API nas últimas 72 horas (editar, apagar) e a URL de mídia inválida ou expirada | Confira os ids e o projeto da chave |
409 | Conflito com o estado atual: rotacionar uma chave já rotacionada, revogada ou expirada; criar chave num projeto inativo; reenviar uma entrega já entregue ou sem payload registrado; criar um template com um nome que já existe; pedir código de pareamento com o número já pareado (already_paired) ou fora de um pareamento (not_pairing, às vezes com Retry-After); editar depois de 15 minutos (edit_window_closed); excluir uma conexão cujo logout falhou | Leia o estado atual antes de repetir |
422 | O proxy informado não passou na verificação | Confira o endereço e as credenciais do proxy |
429 | Um limite foi atingido | Veja qual limite foi |
501 | O provedor da conexão não oferece a operação (error: unsupported_by_provider) | Use outra operação ou outra conexão |
503 | A instância do gateway que atende a conexão está mudando (um reinício, uma troca), com Retry-After; ou, ao definir um proxy, o gateway está sem a chave de criptografia das credenciais | Espere Retry-After segundos e repita. Sem Retry-After, fale com o suporte |
500 e outros 5xx | Falha do gateway | Repita com espera crescente |
429: qual limite foi
O mesmo status cobre limites diferentes. Os cabeçalhos e o corpo dizem qual foi:
| Limite | Como reconhecer | O que fazer |
|---|---|---|
| Requisições por IP: 600 por minuto, somadas de todas as chaves que saem do mesmo IP | Retry-After; corpo { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded, retry in 1 minute" } | Espere Retry-After segundos e diminua o ritmo |
| Falhas de autenticação: 20 chaves erradas em 5 minutos, por IP | Retry-After; error: "Too many failed authentication attempts" | Corrija a chave. Enquanto durar, só as chaves erradas recebem 429; a chave certa continua funcionando |
| Cota do plano (só no envio, e só em planos com limite de mensagens: o LITE e o PRO não têm): o limite diário ou mensal de mensagens da organização, somando as enviadas e as que estão na fila | 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. A partir de 80% do limite, os envios aceitos trazem X-Usage-Warning: acompanhe esse cabeçalho para não chegar aqui |
| Destinatários novos (só no envio): o número já alcançou o limite de pessoas novas das últimas 24 horas | Retry-After; error: new_recipient_cap_reached | Mensagens para contatos conhecidos continuam sendo aceitas. Para os novos, espere Retry-After. Veja Limites de envio |
| Código de pareamento (só no código de pareamento): um código pedido para a conexão há menos de 30 segundos, ou 5 códigos para o mesmo número na última hora | Retry-After; error: pairing_code_too_soon | Espere Retry-After: cada código gera um aviso no celular |
| Verificações de proxy (só em Definir proxy): até 60 por hora por organização | Retry-After | Espere Retry-After |
Os números acima são os padrões do gateway. Todos os limites, com os de ritmo por número, estão em Limites.
Para ver o status e os cabeçalhos de uma resposta, use -i no cURL:
curl -si -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "5511988887777", "message": "Olá!", "clientRef": "pedido-1234"}'HTTP/1.1 429 Too Many Requests
X-Usage-Percent: 110
Content-Type: application/json
{"error":"Daily message limit exceeded (1100/1000)"}Repetir com segurança
Retry-Afterpresente (429e503, e o409 not_pairingquando os QR codes estão terminando): espere esse número de segundos e repita.5xxsemRetry-After, timeouts e erros de rede: repita com espera crescente (1 s, 2 s, 4 s…) e um número máximo de tentativas.429semRetry-After(a cota de um plano com limite de mensagens): não repita; avise quem opera o sistema.- Outros
4xx: repetir não muda nada. Corrija a causa antes.
Nos envios, mande sempre um clientRef. Repetir um POST /connections/{id}/send que talvez tenha funcionado (um timeout, uma conexão caída) não duplica a mensagem: a repetição de um envio aceito responde 200 com duplicate: true e o job original, nunca um erro de conexão ou de cota. Veja Idempotência.
// Node.js 18+: fetch nativo
const BASE = 'https://api.apiwpp.com'
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
async function send(connectionId, body, maxAttempts = 5) {
for (let attempt = 1; ; attempt++) {
let res
try {
res = await fetch(`${BASE}/connections/${connectionId}/send`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify(body), // com clientRef: repetir não duplica
})
} catch (networkError) {
if (attempt >= maxAttempts) throw networkError
await sleep(1000 * 2 ** (attempt - 1))
continue
}
if (res.ok) return res.json() // 202 na fila, ou 200 com duplicate: true
const error = await res.json().catch(() => ({}))
const retryAfter = Number(res.headers.get('retry-after'))
const id = error.code ?? error.error
if (attempt < maxAttempts && retryAfter > 0) {
await sleep(retryAfter * 1000) // 429 e 503 com Retry-After
continue
}
if (attempt < maxAttempts && res.status >= 500) {
await sleep(1000 * 2 ** (attempt - 1))
continue
}
throw Object.assign(new Error(`HTTP ${res.status}: ${id}`), { status: res.status, body: error })
}
}
await send(process.env.CONNECTION_ID, {
to: '5511988887777',
message: 'Olá! Sua consulta está confirmada.',
clientRef: 'pedido-1234',
})# pip install requests
import os
import time
import requests
BASE = "https://api.apiwpp.com"
def send(connection_id, body, max_attempts=5):
for attempt in range(1, max_attempts + 1):
last = attempt == max_attempts
try:
res = requests.post(
f"{BASE}/connections/{connection_id}/send",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json=body, # com clientRef: repetir não duplica
timeout=30,
)
except requests.RequestException:
if last:
raise
time.sleep(2 ** (attempt - 1))
continue
if res.ok:
return res.json() # 202 na fila, ou 200 com duplicate: true
retry_after = int(res.headers.get("Retry-After", "0") or 0)
if not last and retry_after > 0:
time.sleep(retry_after) # 429 e 503 com Retry-After
continue
if not last and res.status_code >= 500:
time.sleep(2 ** (attempt - 1))
continue
res.raise_for_status()
send(os.environ["CONNECTION_ID"], {
"to": "5511988887777",
"message": "Olá! Sua consulta está confirmada.",
"clientRef": "pedido-1234",
})Próximos passos
- Códigos de erro: cada identificador, onde aparece e o que fazer.
- Limites de envio: o ritmo por número, o aquecimento e os destinatários novos.
- Idempotência: o
clientRefe omessage.send_failed. - Cabeçalhos:
Retry-After,X-Usage-PercenteX-Usage-Warning.