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.
| 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. |
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. |
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. |
| 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. |
| ”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:- The full response body — it always carries
error.codeanderror.message. - The timestamp of the request (UTC, second precision is enough).
- The endpoint and method (
POST /api/v1/leads, etc.). - For webhook issues, the
X-FlowEstate-Deliveryheader value. - The first 8 chars of your API key (
fe_k_a1b2c3d4) — not the full key. We can identify which one without seeing the secret.
Health and incidents
Check status.flowestate.app before deep-debugging an outage. If a planned maintenance window is in effect, intermittent503 responses are expected.