Pular para o conteúdo

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.

Ver em Markdown

Todo erro responde um status HTTP e um corpo JSON com pelo menos o campo error:

jsonO corpo mínimo
{ "error": "Connection not ready (status: close)" }

Alguns erros trazem mais campos:

CampoQuando aparece
errorSempre. Um texto para pessoas ou, em alguns casos, um identificador estável em snake_case (veja abaixo)
messageOs detalhes, nos erros de validação, de limite e de pareamento
statusCodeRepete o status HTTP nos erros de validação do schema e no limite de requisições
codeUm identificador estável: FST_ERR_VALIDATION, subscription_inactive, number_limit_reached, plan_feature_required, edit_window_closed, not_on_whatsapp
featureCom plan_feature_required: o recurso que o plano da organização não tem
missingVariablesNum envio com template: as variáveis que faltaram
400
{
  "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.

OndeIdentificadorStatusOperação
codeFST_ERR_VALIDATION400Qualquer uma: o corpo, o caminho ou a query não seguem o schema
codenot_on_whatsapp400Editar mensagem, Apagar mensagem, Marcar como lidas e Mostrar presença
codesubscription_inactive402As operações que usam a sessão do WhatsApp do número
codenumber_limit_reached402Criar conexão e Criar conexão no projeto
codeplan_feature_required403As operações PRO de mensagem (editar, apagar, marcar como lidas, presença)
codeedit_window_closed409Editar mensagem
errorinvalid_recipient400Enviar mensagem
erroralready_paired, not_pairing409Código de pareamento
errornew_recipient_cap_reached429Enviar mensagem
errorpairing_code_too_soon429Código de pareamento
errorunsupported_by_provider501As operações que o provedor da conexão não oferece

Os status

StatusQuandoO que fazer
400A 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
401Sem 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
402A 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
403A 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 elaUse uma chave com o escopo, ou um plano com o recurso. Veja Escopos
404O 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 expiradaConfira os ids e o projeto da chave
409Conflito 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 falhouLeia o estado atual antes de repetir
422O proxy informado não passou na verificaçãoConfira o endereço e as credenciais do proxy
429Um limite foi atingidoVeja qual limite foi
501O provedor da conexão não oferece a operação (error: unsupported_by_provider)Use outra operação ou outra conexão
503A 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 credenciaisEspere Retry-After segundos e repita. Sem Retry-After, fale com o suporte
500 e outros 5xxFalha do gatewayRepita com espera crescente

429: qual limite foi

O mesmo status cobre limites diferentes. Os cabeçalhos e o corpo dizem qual foi:

LimiteComo reconhecerO que fazer
Requisições por IP: 600 por minuto, somadas de todas as chaves que saem do mesmo IPRetry-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 IPRetry-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 filaX-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. 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 horasRetry-After; error: new_recipient_cap_reachedMensagens 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 horaRetry-After; error: pairing_code_too_soonEspere Retry-After: cada código gera um aviso no celular
Verificações de proxy (só em Definir proxy): até 60 por hora por organizaçãoRetry-AfterEspere 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:

bashStatus e cabeçalhos de um envio
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"}'
429
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-After presente (429 e 503, e o 409 not_pairing quando os QR codes estão terminando): espere esse número de segundos e repita.
  • 5xx sem Retry-After, timeouts e erros de rede: repita com espera crescente (1 s, 2 s, 4 s…) e um número máximo de tentativas.
  • 429 sem Retry-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',
})

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026