Los rate limits se aplican por API key, por minuto:
| Plan | Solicitudes / minuto |
|---|
| 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 incluye:
Retry-After — segundos a esperar antes de reintentar. Usa este valor, no hardcodees delays.X-RateLimit-Limit — el techo por minuto para esta key.X-RateLimit-Remaining — siempre 0 en un 429.
Buenas prácticas
Respeta Retry-After. Pausa por esa cantidad de segundos y luego reintenta el mismo request.
- Distribuye operaciones masivas. Si vas a importar 50,000 leads, no los dispares en un loop apretado. A 1000/min puedes empujar de forma sostenible ~16 leads/segundo; apunta a 10/segundo para tener margen.
- Una key por worker. Si tienes workers en paralelo, cada uno tiene su propio presupuesto. Una key compartida los cuello-de-botella a todos.
- Cachea lookups de catálogo (
/lead-sources, /pipeline/stages, /webhooks/events) en lugar de pegarles en cada request — cambian poco.
- Agrupa lecturas con el filtro
query en lugar de hacer N llamadas individuales GET /leads/{id} cuando necesites consultar varios leads.
Cuando chocas con el techo
Si tu integración legítimamente necesita más de lo que da el plan paid, contacta a soporte@flowestate.app — los límites se pueden ajustar para clientes de alto volumen, por organización. 
