# Rate limits

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

Source: https://oltinid.com/docs/reference/rate-limits/ · Section: Reference · All OneiD documentation: https://oltinid.com/llms.txt

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
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

- [Errors and troubleshooting](https://oltinid.com/docs/reference/errors/)
- [Client credentials for services](https://oltinid.com/docs/guides/client-credentials/)
- [Refresh tokens](https://oltinid.com/docs/guides/refresh-tokens/)