> ## 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.

# Best Practices & FAQ

> Operational best practices for the Pilot Status API — error handling, retries, webhook usage, key security — plus quick answers to common errors.

## Integration and operations

* Validate that the WhatsApp number is connected before testing sends.
* For any non-2xx response, record the `statusCode` and response body — it makes debugging much easier.
* For `429` and `5xx` errors, retry with **exponential backoff and jitter**.
* Use webhooks to observe the full lifecycle (`sent`/`delivered`/`read`/`failed`) in real time instead of polling.

## Security

* Keep the API key on the **backend only** — never ship it to a browser or mobile app.
* Avoid logging sensitive data (the full key, or message content if your policy requires).

## Quick FAQ

### Got `403` with code `TENANT_SCOPE_NOT_ALLOWED`

You used a **tenant-scoped** key on a per-number endpoint (e.g. `POST /v1/messages/send`). Use the **number-scoped** key from the **API Keys** page (`/api-keys`) instead.

### Got `403` with code `NUMBER_SCOPE_NOT_ALLOWED`

You used a **number-scoped** key on a tenant-only endpoint (e.g. `/v1/numbers/*`, `/v1/branding`). Use the **tenant-scoped** key from **Profile → API**.

### `READ` status / `message.read` never arrives

The read event only fires when the recipient has **WhatsApp read receipts** enabled (Settings → Privacy). Otherwise the lifecycle stops at `DELIVERED` — this is a WhatsApp behavior, not a delivery failure.

## Related

* [WhatsApp Blocks & Bans](/trust/whatsapp-blocks)
* [Webhooks](/concepts/webhooks)
* [API Authentication](/api/authentication)