Límites de tasa (rate limits) de la API y encabezados de cuota

Para proteger la plataforma de abusos y garantizar buen desempeño para todos, cada organización tiene un límite de solicitudes por minuto (rate limit) a la API, según su plan de suscripción. El límite aplica por (usuario + organización) o por token, según cómo te autentiques.

Límites por plan

Si tu organización usa un plan no reconocido o de prueba, se aplica un tope de seguridad de 300 req/min.

Encabezados de cuota

Cada respuesta exitosa incluye:

• X-RateLimit-Limit: el tope de tu plan (solicitudes/minuto).
• X-RateLimit-Remaining: cuántas solicitudes te quedan en el minuto actual.

Cuando superás el límite, la API responde 429 Too Many Requests con:

• Retry-After: segundos que debés esperar antes de reintentar.
• X-RateLimit-Reset: timestamp Unix en que se reinicia la cuota.

Ejemplo: leer la cuota restante

curl -i -X GET "https://app.omnifox.io/api/v1/contacts" \
  -H "Authorization: Bearer TU_TOKEN" | grep -i ratelimit

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587

Consejos

• Si tu integración hace polling frecuente (por ejemplo, revisar mensajes nuevos), preferí procesar Webhooks salientes en vez de consultar la API a intervalos cortos: consumís mucho menos cuota.
• Diseñá tu cliente para respetar Retry-After con backoff exponencial en vez de reintentar inmediatamente.

Solución de problemas

• 429 constante aunque tu volumen es bajo: varios procesos o scripts pueden estar compartiendo el mismo usuario/token; cada uno consume del mismo bucket.
• Necesitás más cuota: subí de plan desde Configuración > Plan y facturación; el límite se recalcula automáticamente en el siguiente minuto.