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 PLAN_LIMIT_REACHED on POST /leads | The organization is at its lead cap. | Upgrade the plan or remove unused leads. Retrying won’t help. See Plan-limit errors. |
403 FORBIDDEN with “You have reached the maximum…” | Plan limit reached on projects or webhook endpoints. | 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. |
POST /leads returns 201 but no new lead appears | The contact already existed, so the call merged instead of creating. | Read outcome in the response: merged means id points at the lead that was already there. |
| Two people from the same company can’t both be created | They’re sharing an email or phone, so they resolve to one contact identity. | Give each one their own email or phone. There’s no way to force a duplicate through the public API. |
A lead’s estimatedValue / notes didn’t update after a repeated post | The merge only fills empty fields; it never overwrites one that already has a value. | Use PUT /leads/{leadId} to overwrite on purpose. |
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 writing the same leads back | The receiver writes to FlowEstate without checking source. | Drop events where X-FlowEstate-Source: api. The loop no longer creates duplicates — the writes merge — but it still burns your rate limit. See Preventing loops. |
Your endpoint suddenly gets far more lead.created / lead.assigned than before | Inbound channels (lead webhooks, Meta lead ads, WhatsApp) used to be silent and now emit like every other channel. | Expected. They carry X-FlowEstate-Source: system. See Where lead events come from. |
| Your endpoint stops receiving events partway through the month, with no error | The organization exhausted its monthly outbound-event allowance. Events are dropped before dispatch, silently. | Upgrade off the Free plan, or reconcile against GET /leads. See Monthly event allowance. |
A lead.assigned arrives with no lead.created before it | A repeated contact merged into an existing unassigned lead, and the round robin then assigned it. | Expected. Handle the two events independently. |
| ”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. |