Límites de tasa de la API

Los 5 niveles

Cada petición pasa por cinco controles. El primero que deniegue gana.

Topes diarios por endpoint

Algunos endpoints tienen límites más ajustados porque consumen un tiempo significativo de CPU o GPU:

Límite de tamaño de archivo

• 200 MB por archivo para la API (frente a 100 MB en el sitio web).
• Algunas herramientas de IA pesadas tienen límites internos menores — por ejemplo upscale-image se limita a 20 MB para mantener los procesos de GPU por debajo de 2 minutos.

Headers en cada respuesta

Cada respuesta exitosa de la API incluye los siguientes headers para que puedas seguir tu cuota sin consultar /api/v1/limits:

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 873
X-RateLimit-Reset-Day: 1775865600     # unix timestamp
X-RateLimit-Limit-Hour: 150
X-RateLimit-Remaining-Hour: 142
X-RateLimit-Limit-Endpoint: 50
X-RateLimit-Remaining-Endpoint: 38

Qué ocurre cuando alcanzas un límite

La API devuelve 429 Too Many Requests con un header Retry-After (en segundos) y un header X-RateLimit-Reason que indica qué nivel se alcanzó:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Reason: cooldown

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (cooldown). Retry after 1 seconds.",
    "details": { "reason": "cooldown", "retry_after": 1 }
  }
}

Valores posibles de X-RateLimit-Reason: cooldown, burst, hourly, daily, endpoint:<name>, banned.

Escalado a ban

El abuso repetido activa un ban temporal. En concreto: 10 denegaciones por rate limit en 1 hora desde la misma IP → ban de 24 horas con HTTP 403 Forbidden y error.code: BANNED.

Si crees que te han baneado injustamente (por ejemplo, porque compartes IP con muchos usuarios), contáctanos en /contact y revisaremos el caso.

Buenas prácticas para evitar el throttling

• Espera al menos 1 segundo entre peticiones consecutivas (o usa el header Retry-After en los 429).
• Usa los endpoints batch para trabajo masivo: POST /api/v1/batch acepta hasta 20 archivos en una sola llamada HTTP (cada archivo sigue contando en tu cuota diaria, pero ahorras viajes de red).
• Vigila los headers: cuando X-RateLimit-Remaining-Day baje de 100, reduce la velocidad o cachea tus resultados.
• Consulta tu uso en cualquier momento con GET /api/v1/limits — este endpoint NO cuenta en tu cuota.
• No reintentes al instante tras un 429 — respeta Retry-After. Los reintentos inmediatos pueden activar el escalado a ban.

¿Necesitas límites más altos?

Los límites actuales son valores por defecto MVP. Observamos el uso real y los ajustaremos según la demanda. Si tienes un caso de uso legítimo que requiera cuotas más altas, escríbenos en /contact.

Un futuro plan de pago podría ofrecer cuotas dedicadas, colas prioritarias y mayor retención de archivos — pero el plan gratuito siempre se mantendrá.