Troubleshooting - FlowEstate Developers

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.code and error.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-Delivery header 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.

Send to soporte@flowestate.app.

Health and incidents

Check status.flowestate.app before deep-debugging an outage. If a planned maintenance window is in effect, intermittent 503 responses are expected.