API
Rate Limiting

Rate Limiting

The Skycloak API enforces per-consumer rate limits to ensure fair use and platform stability.

Limits

Window Limit
Per second 5 requests
Per minute 300 requests
Per hour 5,000 requests
Per day 25,000 requests

Rate limits are applied per workspace.

Response Headers

Every API response includes rate limit headers. The IETF standard headers reflect the most restrictive active window:

Header Description
RateLimit-Limit Maximum requests allowed in the current window
RateLimit-Remaining Requests remaining in the current window
RateLimit-Reset Seconds until the current window resets

Per-window headers give granular visibility into each time window:

Header Description
X-RateLimit-Limit-Second Per-second request limit
X-RateLimit-Remaining-Second Requests remaining this second
X-RateLimit-Limit-Minute Per-minute request limit
X-RateLimit-Remaining-Minute Requests remaining this minute
X-RateLimit-Limit-Hour Per-hour request limit
X-RateLimit-Remaining-Hour Requests remaining this hour
X-RateLimit-Limit-Day Per-day request limit
X-RateLimit-Remaining-Day Requests remaining today

Example headers:

RateLimit-Limit: 5
RateLimit-Remaining: 3
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 5
X-RateLimit-Remaining-Second: 3
X-RateLimit-Limit-Minute: 300
X-RateLimit-Remaining-Minute: 287
X-RateLimit-Limit-Hour: 5000
X-RateLimit-Remaining-Hour: 4980
X-RateLimit-Limit-Day: 25000
X-RateLimit-Remaining-Day: 24960

Handling 429 Responses

When you exceed a limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait:

Retry-After: 1
{
  "type": "https://skycloak.io/docs/api/errors#rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "detail": "Rate limit exceeded. Retry after 1 second.",
  "status": 429
}

Retry Strategy

Always retry 429 responses — respect the Retry-After header value. For transient server errors (500, 503), use exponential backoff with jitter:

  1. Wait for the Retry-After duration (for 429) or start with 1s (for 5xx)
  2. Double the delay on each subsequent retry
  3. Cap the delay at a maximum (e.g., 32s)
  4. Add random jitter to avoid thundering-herd problems

Never retry 4xx errors other than 429 — they indicate a problem with the request itself.

Last updated on
Error HandlingVersioning