Saltar al contenido
CA ES
Solicitar una demo

Desarrolladores

Límites de ritmo

120 peticiones por minuto por credencial, cabeceras X-RateLimit y cómo reintentar tras un 429.

Para proteger el servicio, cada credencial puede hacer 120 peticiones por minuto. El límite es por credencial: dos credenciales de un mismo club tienen contadores independientes.

Cabeceras

Las respuestas autenticadas que llegan al limitador incluyen:

Cabecera Significado
X-RateLimit-Limit Peticiones permitidas por minuto (120).
X-RateLimit-Remaining Peticiones que te quedan en la ventana actual.
X-RateLimit-Reset Instante en que se reinicia la ventana, como timestamp Unix en segundos.

No aparecen en las respuestas 401 ni en 403 feature_disabled, porque esas peticiones se rechazan antes de contar.

curl -s -i "$PRANARP_URL/api/v1/me" -H "Authorization: Bearer $PCK_TOKEN" | grep -i '^x-ratelimit'

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1792692060

Cuando te pasas: 429

Al superar el límite recibes 429 con el código rate_limited, las cabeceras X-RateLimit-* (con Remaining: 0) y Retry-After, con los segundos que debes esperar:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792692083

{
  "error": { "code": "rate_limited", "message": "Too many requests.", "details": {} }
}

Cómo reintentar

  1. Si hay Retry-After, espera ese tiempo antes de volver a intentarlo.
  2. Si no, usa espera exponencial con algo de aleatoriedad (1 s, 2 s, 4 s…).
  3. En las creaciones, reutiliza la misma Idempotency-Key para no duplicar.

Un ejemplo sencillo en shell:

for attempt in 1 2 3 4 5; do
  status=$(curl -s -o /tmp/out.json -D /tmp/headers.txt -w '%{http_code}' \
    "$PRANARP_URL/api/v1/spaces" -H "Authorization: Bearer $PCK_TOKEN")
  [ "$status" != "429" ] && break
  wait=$(grep -i '^retry-after:' /tmp/headers.txt | tr -dc '0-9')
  sleep "${wait:-$((2 ** attempt))}"
done

Cómo no llegar al límite

  • Usa los webhooks en lugar de consultar el listado de reservas cada pocos segundos.
  • Pide páginas grandes (limit=200) en vez de muchas pequeñas; ver paginación.
  • Cachea los espacios, que cambian poco.
  • Vigila X-RateLimit-Remaining y reduce el ritmo antes de llegar a cero.

Si tu caso de uso necesita un límite mayor, escríbenos a hello@pranarp.com contando qué integras y con qué volumen.