> ## 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 ".") 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. # Erros > Formato do erro, códigos HTTP e todos os códigos de erro da API e do webhook delivery. Toda resposta de erro tem o mesmo corpo. `code` é estável e feito para o seu código tratar; `message` é para humanos e pode mudar. ```json theme={"system"} { "error": { "code": "instance_not_connected", "message": "Instance is not connected", "details": {} } } ``` `details` é opcional (em `invalid_request` traz `issues` com o caminho de cada campo inválido). ## Códigos HTTP | HTTP | Quando | | ----- | ------------------------------------------------------------------------- | | `400` | Body ou parâmetro inválido (`invalid_request`, `invalid_phone`) | | `401` | Instância/token errados ou `Client-Token` ausente | | `402` | Período de teste vencido ou assinatura inativa (só em endpoints de envio) | | `403` | IP fora da allowlist do workspace | | `404` | Recurso não encontrado (chat, grupo, produto, etiqueta…) | | `409` | Estado incompatível: instância desconectada, fila cheia, fila desligada | | `429` | Limite de requisições da instância | | `5xx` | Falha interna ou engine indisponível — tente de novo com backoff | ## Códigos de erro ### Autenticação e acesso | `code` | HTTP | Significado | | ----------------------- | ---- | -------------------------------------------------------------------------------------- | | `unauthorized` | 401 | Faltou `instance_id` ou `token` na URL | | `instance_not_found` | 401 | Instância não existe ou token não confere (404 quando o erro vem de uma ação imediata) | | `client_token_required` | 401 | Workspace exige o header `Client-Token` e ele está ausente ou errado | | `ip_not_allowed` | 403 | IP de origem fora da [allowlist](/security/ip-allowlist) | | `subscription_required` | 402 | Teste vencido ou assinatura inativa; assine no painel | | `rate_limited` | 429 | Veja `Retry-After` e [Rate limit](/api-reference/pagination-and-limits) | ### Request e estado da instância | `code` | HTTP | Significado | | ----------------------------------- | ---- | ------------------------------------------------------------------- | | `invalid_request` | 400 | Validação do body/query falhou (`details.issues`) | | `invalid_phone` | 400 | `phone` fora do formato aceito | | `not_found` | 404 | Recurso genérico não encontrado (ex.: QR code indisponível) | | `instance_not_connected` | 409 | Ação imediata com a instância fora do ar | | `instance_starting` | 409 | Sessão ainda carregando; tente em alguns segundos | | `instance_already_connected` | 409 | Pareamento pedido com o número já conectado | | `queue_full` | 409 | Mais de 1.000 mensagens aguardando nesta instância | | `queue_disabled_while_disconnected` | 409 | `disable_enqueue_when_disconnected` ligado e instância desconectada | | `engine_unavailable` | 503 | O nó que hospeda a instância não respondeu | | `internal` | 500 | Erro inesperado | ### Erros de operação (ações imediatas ou webhook `delivery`) Estes aparecem como resposta HTTP nas ações imediatas e em `error_code` no webhook [`delivery`](/api-reference/webhooks/delivery) quando um envio falha. | `code` | HTTP (ação imediata) | Significado | | ------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `phone_not_on_whatsapp` | 404 | O número não tem WhatsApp | | `send_failed` | 502 | O WhatsApp recusou o envio | | `send_timeout` | 504 | O aparelho não confirmou o envio a tempo | | `not_allowed` | 403 | A conta não pode executar a ação (ex.: enviar para quem te bloqueou, admin necessário) | | `shadow_ban` | 403 | O WhatsApp aceitou o envio mas as mensagens não estão chegando; pare os envios e veja [Boas práticas](/guides/best-practices) | | `group_suspended` | 403 | Grupo suspenso pelo WhatsApp | | `media_download_failed` | 422 | O engine não conseguiu baixar a URL de mídia informada | | `media_invalid` | 400 | Mídia acima do limite ou em formato não aceito | | `message_not_found` | 404 | A mensagem referenciada (responder, encaminhar, editar, votar) não está no cache do engine — veja [Fila e reenvio](/guides/queue-and-retries) | | `group_not_found` / `chat_not_found` / `newsletter_not_found` | 404 | Id inválido ou a conta não participa | | `invite_link_invalid` | 400 | Link de convite inválido ou revogado | | `product_not_found` / `order_not_found` / `label_not_found` | 404 | Recurso de catálogo/etiqueta inexistente | | `action_failed` | 502 | O aparelho respondeu com erro genérico; repetir costuma resolver | ## Como tratar * **`429`**: espere `Retry-After` segundos. O limite é por instância; distribua envios em várias instâncias se precisar de mais. * **`409 instance_not_connected`**: consulte `GET /status`; se `status` for `qr` ou `logged_out`, o número precisa ler o QR de novo. Envios enfileirados não sofrem disso. * **`402`**: leitura e webhooks continuam funcionando; só os envios param até a assinatura. * **`5xx` e timeouts de rede**: repita com backoff exponencial. Envios são seguros de repetir? **Não automaticamente** — se a primeira chamada chegou, você mandaria duas mensagens. Guarde o `wabox_id` da resposta antes de repetir e confirme pelo webhook `delivery` ou por `GET /queue`.