# Erros

Fonte: https://apiwpp.com/docs/guias/erros
Seção: Guias
Atualizado em: 2026-09-29

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`:

**O corpo mínimo**

```json
{ "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 |

Resposta `400`

```json
{
  "statusCode": 400,
  "code": "FST_ERR_VALIDATION",
  "error": "Bad Request",
  "message": "body must have required property 'to'"
}
```

> **Decida pelo status, não pelo texto**
>
> O texto livre de `error` e de `message` é para pessoas e pode mudar. Decida pelo status HTTP e, quando houver, pelo identificador: o campo `code` ou, nos erros listados abaixo, o próprio `error` em snake_case. Nunca compare frases.

## 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](https://apiwpp.com/docs/referencia/codigos-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](https://apiwpp.com/docs/api/mensagens/editar-mensagem), [Apagar mensagem](https://apiwpp.com/docs/api/mensagens/apagar-mensagem), [Marcar como lidas](https://apiwpp.com/docs/api/mensagens/marcar-como-lidas) e [Mostrar presença](https://apiwpp.com/docs/api/mensagens/mostrar-presenca) |
| `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](https://apiwpp.com/docs/api/conexoes/criar-conexao) e [Criar conexão no projeto](https://apiwpp.com/docs/api/projetos/criar-conexao-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](https://apiwpp.com/docs/api/mensagens/editar-mensagem) |
| `error` | `invalid_recipient` | `400` | [Enviar mensagem](https://apiwpp.com/docs/api/mensagens/enviar-mensagem) |
| `error` | `already_paired`, `not_pairing` | `409` | [Código de pareamento](https://apiwpp.com/docs/api/conexoes/codigo-de-pareamento) |
| `error` | `new_recipient_cap_reached` | `429` | [Enviar mensagem](https://apiwpp.com/docs/api/mensagens/enviar-mensagem) |
| `error` | `pairing_code_too_soon` | `429` | [Código de pareamento](https://apiwpp.com/docs/api/conexoes/codigo-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](https://apiwpp.com/docs/referencia/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](https://apiwpp.com/docs/guias/erros#429-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](https://apiwpp.com/docs/api/mensagens/enviar-mensagem), 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](https://apiwpp.com/docs/api/mensagens/enviar-mensagem)): 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](https://apiwpp.com/docs/guias/limites-de-envio) |
| **Código de pareamento** (só no [código de pareamento](https://apiwpp.com/docs/api/conexoes/codigo-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](https://apiwpp.com/docs/api/conexoes/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](https://apiwpp.com/docs/referencia/limites).

Para ver o status e os cabeçalhos de uma resposta, use `-i` no cURL:

**Status e cabeçalhos de um envio**

```bash
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"}'
```

Resposta `429`

```http
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](https://apiwpp.com/docs/guias/idempotencia).

> **Só o envio é idempotente**
>
> A API não tem cabeçalho `Idempotency-Key`: a idempotência é o campo `clientRef` do envio. Nas outras operações que criam algo (uma conexão, uma chave, um template), consulte o estado antes de repetir uma requisição cuja resposta se perdeu, para não criar duas vezes.

**Node.js**

```javascript
// 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',
})
```

**Python**

```python
# 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",
})
```

> **Dica**
>
> Um envio aceito (`202`) ainda pode não acontecer: o número pode não estar no WhatsApp, ou as tentativas podem se esgotar. Esses casos não voltam como erro HTTP, e sim como o evento [`message.send_failed`](https://apiwpp.com/docs/webhooks/message-send-failed), que só chega para envios com `clientRef`.

## Próximos passos

- [Códigos de erro](https://apiwpp.com/docs/referencia/codigos-de-erro): cada identificador, onde aparece e o que fazer.
- [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio): o ritmo por número, o aquecimento e os destinatários novos.
- [Idempotência](https://apiwpp.com/docs/guias/idempotencia): o `clientRef` e o `message.send_failed`.
- [Cabeçalhos](https://apiwpp.com/docs/referencia/cabecalhos): `Retry-After`, `X-Usage-Percent` e `X-Usage-Warning`.
