> ## Documentation Index
> Fetch the complete documentation index at: https://developer.wabox.me/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Wabox é uma API não-oficial de WhatsApp (aparelho vinculado). Tudo é snake_case; a base é https://api.wabox.me/instances/{instance_id}/token/{token}.
> Envios respondem { id, message_id, wabox_id, status: "queued" } na hora; o resultado real chega no webhook delivery. Envios não são idempotentes: confira GET /queue antes de repetir.
> Sempre verifique X-Wabox-Signature (HMAC-SHA256 de "<t>.<corpo cru>") nos webhooks e deduplique por event_id.
> Botões, listas, carrossel e catálogo são best effort e não renderizam no WhatsApp Web/Desktop. Não existem: chamadas, listas de transmissão, histórico de mensagens, instância mobile.
> Não invente endpoints ou campos: use o OpenAPI em https://api.wabox.me/openapi.json.

# Rate limit e tratamento de erros

> Como dimensionar o cliente HTTP, quando repetir uma chamada e quando não.

A referência completa de códigos está em [Erros](/api-reference/errors) e os números em [Paginação, rate limit e limites](/api-reference/pagination-and-limits). Esta página é sobre **o que fazer** com eles.

## Regra geral

| Situação                                 | Repetir?         | Como                                                                                                             |
| ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `429 rate_limited`                       | Sim              | Espere `Retry-After` segundos (inteiro, geralmente 1)                                                            |
| `5xx`, timeout de rede, conexão recusada | Sim, com cuidado | Backoff exponencial (1 s, 2 s, 4 s…) até \~5 tentativas. Em envios, confira `GET /queue` antes para não duplicar |
| `409 instance_not_connected`             | Depois           | Consulte `GET /status`; espere `connected` ou avise o operador                                                   |
| `409 queue_full`                         | Depois           | Espere a fila esvaziar (`GET /queue`) ou use outra instância                                                     |
| `409 instance_starting`                  | Sim              | Alguns segundos depois                                                                                           |
| `400`, `401`, `402`, `403`, `404`        | Não              | É bug no request, credencial ou estado — repetir dá o mesmo resultado                                            |

## Envios não são idempotentes

Repetir um `POST /send-text` que já chegou envia duas mensagens. Quando uma chamada falha por rede **sem** você ler a resposta:

1. Consulte `GET /queue` filtrando pelo `phone` — se a mensagem estiver lá, chegou.
2. Se você tem webhook `delivery`, espere alguns segundos: ele confirma o envio pelo `message_id`.
3. Só então reenvie.

Para tornar isso simples, gere um id próprio por mensagem no seu sistema e registre `wabox_id` assim que a resposta chegar.

## Dimensionando o cliente

* O limite é **por instância**: 60 req/s sustentadas, rajadas de 120. Poucas integrações chegam perto disso; o gargalo real de envio é o intervalo anti-ban da fila.
* Use conexões HTTP keep-alive e um pool pequeno. Centenas de conexões simultâneas para a mesma instância só disputam o mesmo bucket.
* Consultas repetitivas (`GET /status` em loop, `GET /qr-code` a cada segundo) contam. Prefira os webhooks `connected`/`disconnected`; se precisar consultar, a cada 10 s é suficiente.
* Timeout de cliente: 30 s é razoável. Ações imediatas falam com o aparelho e podem levar alguns segundos; envios respondem em milissegundos.

## Lendo os headers

```http theme={"system"}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 1
Content-Type: application/json

{ "error": { "code": "rate_limited", "message": "Too many requests" } }
```

`X-RateLimit-Remaining` vem em todas as respostas; use para desacelerar antes de bater no 429.

## Erros de validação

`400 invalid_request` traz `details.issues` com o caminho de cada campo:

```json theme={"system"}
{ "error": { "code": "invalid_request", "message": "phone: Invalid input", "details": { "issues": [{ "path": "phone", "message": "Invalid input" }] } } }
```

Os casos mais comuns: `phone` com `+`, espaços ou traços (envie só dígitos), `message` vazio, base64 com prefixo errado, `delay_typing` acima de 15.

## Registrando para depurar

Guarde, por chamada: rota, `wabox_id`/`message_id` da resposta, status HTTP e `error.code`. Nos webhooks, guarde `event_id`. Com isso o suporte consegue cruzar com os logs do Wabox.