Rate limits are enforced per API key, per minute:
| Plan | Requests / minute |
|---|
| Free | 60 |
| Paid | 1000 |
429 Too Many Requests:
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
{
"error": {
"message": "Rate limit exceeded. Retry after 23 seconds.",
"code": "BAD_REQUEST"
}
}
429 response includes:
Retry-After — seconds to wait before retrying. Use this value, don’t hardcode delays.X-RateLimit-Limit — the per-minute ceiling for this key.X-RateLimit-Remaining — always 0 on a 429.
Best practices
Honor Retry-After. Pause for that many seconds, then retry the exact same request.
- Spread bulk operations. If you’re importing 50,000 leads, don’t fire them in a tight loop. At 1000/min you can sustainably push ~16 leads/second; aim for 10/second to leave headroom.
- Use one key per worker. If you have parallel workers, each one gets its own budget. One shared key bottlenecks them all.
- Cache catalog lookups (
/lead-sources, /pipeline/stages, /webhooks/events) instead of hitting them on every request — they change rarely.
- Batch reads with the
query filter instead of N individual GET /leads/{id} calls when you need to look up several leads.
When you hit the wall
If your integration legitimately needs more than the paid tier provides, contact soporte@flowestate.app — limits can be adjusted for high-volume customers on a per-organization basis. 
