La API limita el número de peticiones por dirección IP y por ventana de tiempo. Superado el límite, la petición se rechaza con 429 sin llegar a ejecutarse: no consume cuota ni produce efectos.
La ventana es de un minuto y el contador arranca en cada minuto de reloj, no en la primera petición. Una ráfaga a caballo entre dos minutos se reparte entre ambos contadores.
Límite aplicable
El límite depende del host que atiende la petición:
| superficie | peticiones por minuto |
|---|---|
API (api.…) | 80 |
| Panel | 80 |
| Documentación | 50 |
| Sitio público | 40 |
Determinadas operaciones aplican límites propios más estrictos por su costo o su sensibilidad —inicio de sesión, envío de OTP, difusiones— y los declaran en su página de referencia.
Respuesta 429
{
"errors": [
{
"status": "429",
"code": "rate_limit_exceeded",
"detail": "Se superó el límite de peticiones."
}
],
"meta": { "version": "1.57.0", "api_version": "v1", "request_id": "e6f7a8b9c0d1" }
}La respuesta incluye las cabeceras necesarias para reintentar sin adivinar:
| cabecera | contenido |
|---|---|
Retry-After | Segundos que faltan para que la ventana se renueve |
X-RateLimit-Limit | Máximo de peticiones de la ventana |
X-RateLimit-Remaining | Peticiones restantes; en un 429 es siempre 0 |
X-RateLimit-Reset | Momento de renovación, en segundos desde el epoch |
Las cabeceras X-RateLimit-* se emiten únicamente en las respuestas 429. Una respuesta correcta no informa del consumo acumulado; para conocerlo está GET /v1/usage/limits.
Tratamiento recomendado
El valor de Retry-After es el único dato necesario para reintentar: esperar ese margen y repetir la petición. Reintentar antes vuelve a consumir contador y prolonga el bloqueo.
Los límites protegen el sistema frente a ráfagas, no frente al volumen total. El volumen mensual lo gobiernan la cuota del plan y sus propios códigos de error, descritos en la taxonomía de errores.