Rate limits

Know which OneiD endpoints are rate limited, the token endpoint defaults, the 429 response and how to retry correctly.

View as Markdown

OneiD limits how many requests a client or browser can send in a short time, to protect sign-in and token issuance from abuse. When you exceed a limit, OneiD answers with HTTP 429 and tells you how long to wait.

What is limited

Area Limited by Default
Token endpoint (/connect/token) IP address 120 requests per minute
Token endpoint (/connect/token) Client and IP address 600 requests per minute
Sign-in IP address and account Limited; values not published
MFA code entry IP address and account Limited; values not published
Password recovery IP address and account Limited; values not published

The token endpoint limits apply by default. The operator of your OneiD deployment may configure different limits; ask your OneiD administrator if you need the values in use.

Account-level protections apply in addition to rate limits. For example, 5 wrong passwords lock a OneiD account for 5 minutes, and 5 wrong MFA codes lock MFA for 15 minutes.

The 429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "slow_down",
  "error_description": "Too many requests. Try again in 12 seconds."
}
Part Description
Status 429 Too Many Requests.
Retry-After header How many seconds to wait before the next request.
error Always slow_down.
error_description The same wait time, in words. Do not parse it; use Retry-After.

Retry correctly

  1. When you receive HTTP 429, read Retry-After and wait at least that many seconds before you send the request again.
  2. If the retry is refused again, wait longer each time (exponential backoff, for example 2, 4, 8 seconds, with some random jitter), and stop after a few attempts.
  3. Do not retry immediately in a loop.
  4. Surface a clear message to the user if a sign-in step is limited, rather than retrying silently.

Stay within the limits

  • Reuse access tokens. Cache an access token until shortly before it expires. Do not request a new token for every API call. This matters most for the client credentials grant.
  • Refresh once. When several parts of your application need a new token at the same time, let one of them refresh and share the result.
  • Spread scheduled jobs. Many services starting at the same moment can hit the per-IP limit together, especially behind one outbound address.
  • Cache discovery and JWKS. Fetch them at startup and refresh them occasionally, not per request.

Learn more