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

# Troubleshooting

> Common errors, what they mean, and how to fix them.

| Symptom                                                                          | Likely cause                                                                   | Fix                                                                                                                                                               |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 UNAUTHORIZED`                                                               | Missing or malformed `Authorization` header.                                   | Send `Authorization: Bearer fe_k_...`, no extra prefix or quotes.                                                                                                 |
| `403 FORBIDDEN` with "Insufficient permissions. Missing scopes: …"               | The API key wasn't created with that scope.                                    | Edit the key's scopes in the dashboard, or create a new key. See [Scopes](/scopes).                                                                               |
| `403 FORBIDDEN` with "You have reached the maximum…"                             | Plan limit reached (leads, projects, webhook endpoints, etc.).                 | Upgrade the organization's plan or remove unused records.                                                                                                         |
| `400 VALIDATION_ERROR` on `POST /leads` with "email: Email or phone is required" | Both `email` and `phone` are missing or empty.                                 | Provide at least one — `""` is treated as missing. See [Create a lead](/api-reference/leads#create-a-lead).                                                       |
| `400 VALIDATION_ERROR` with "email: Invalid email"                               | Email field contains markdown link syntax or extra characters.                 | Send a clean `user@domain.com` value. Watch out for chat clients auto-formatting addresses.                                                                       |
| `404 NOT_FOUND` on a resource you know exists                                    | The resource belongs to a different organization than the bearer is bound to.  | Use a key from the right organization. Each key is org-scoped.                                                                                                    |
| `429` returned even though you're not in a tight loop                            | Multiple workers sharing one key.                                              | Use one key per worker — each gets its own per-minute budget.                                                                                                     |
| Webhook signature doesn't match                                                  | Using parsed JSON instead of raw body, or wrong secret.                        | Hash the **raw** request body bytes; the secret is the value returned at subscription creation. See [Verifying the signature](/webhooks#verifying-the-signature). |
| Make / Zapier retries the same webhook repeatedly                                | Receiver returning non-`2xx`.                                                  | Return `2xx` even when ignoring the event (e.g. `X-FlowEstate-Source: api`).                                                                                      |
| Receiver gets stuck in a loop, creating duplicate leads                          | The receiver writes to FlowEstate without checking source.                     | Drop events where `X-FlowEstate-Source: api`. See [Preventing loops](/webhooks#preventing-loops).                                                                 |
| "Token is not bound to an organization" on OAuth                                 | OAuth token from a Zapier/Make account that hasn't picked an organization yet. | End user must complete the consent / org-selection flow once in the connector.                                                                                    |

## Capturing diagnostics

When opening a support ticket include:

1. The full **response body** — it always carries `error.code` and `error.message`.
2. The **timestamp** of the request (UTC, second precision is enough).
3. The **endpoint** and **method** (`POST /api/v1/leads`, etc.).
4. For webhook issues, the **`X-FlowEstate-Delivery`** header value.
5. The **first 8 chars** of your API key (`fe_k_a1b2c3d4`) — *not the full key*. We can identify which one without seeing the secret.

Send to [soporte@flowestate.app](mailto:soporte@flowestate.app).

## Health and incidents

Check [status.flowestate.app](https://status.flowestate.app) before deep-debugging an outage. If a planned maintenance window is in effect, intermittent `503` responses are expected.