> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Boas Práticas e FAQ

> Boas práticas operacionais para a API do Pilot Status — tratamento de erros, tentativas, uso de webhooks, segurança de chaves — além de respostas rápidas para erros comuns.

## Integração e operações

* Valide que o número de WhatsApp está conectado antes de testar envios.
* Para qualquer resposta não-2xx, registre o `statusCode` e o corpo da resposta — isso facilita muito a depuração.
* Para erros `429` e `5xx`, tente novamente com **backoff exponencial e jitter**.
* Use webhooks para observar todo o ciclo de vida (`sent`/`delivered`/`read`/`failed`) em tempo real, em vez de fazer polling.

## Segurança

* Mantenha a chave de API **apenas no backend** — nunca a envie para um navegador ou aplicativo móvel.
* Evite registrar dados sensíveis (a chave completa ou o conteúdo das mensagens, se sua política exigir).

## FAQ rápido

### Recebi `403` com o código `TENANT_SCOPE_NOT_ALLOWED`

Você usou uma chave com **escopo de tenant** em um endpoint por número (ex.: `POST /v1/messages/send`). Use a chave com **escopo de número** da página **API Keys** (`/api-keys`).

### Recebi `403` com o código `NUMBER_SCOPE_NOT_ALLOWED`

Você usou uma chave com **escopo de número** em um endpoint exclusivo de tenant (ex.: `/v1/numbers/*`, `/v1/branding`). Use a chave com **escopo de tenant** em **Perfil → API**.

### O status `READ` / `message.read` nunca chega

O evento de leitura só é disparado quando o destinatário tem os **recibos de leitura do WhatsApp** ativados (Configurações → Privacidade). Caso contrário, o ciclo de vida para em `DELIVERED` — isso é um comportamento do WhatsApp, não uma falha de entrega.

## Relacionados

* [Bloqueios e Banimentos do WhatsApp](/pt-BR/trust/whatsapp-blocks)
* [Webhooks](/pt-BR/concepts/webhooks)
* [Autenticação da API](/pt-BR/api/authentication)