Rate limits

The windows

Limits are counted within a fixed window, per calling address unless a row says otherwise, and the bucket depends on the path:

The numbers are deployment configuration with these defaults; a deployment may tighten them. Read the headers rather than hard-coding the table.

The OAuth and userinfo buckets

The sign-in journey is three buckets, not one. The token endpoint is keyed by your client id, so every server of one application shares 600 per minute wherever it runs, and one noisy application cannot spend another's. A request that names no client id falls back to the address.

Approving a consent spends a grant, so it is kept tight: 30 per 10 minutes per address. Everything else under `/v1/oauth/` — the authorize redirect, the hosted interaction, the cross-device status poll, a cancel — shares 300 per minute** per address, sized for an office of people behind one network polling every few seconds.

`/v1/userinfo` is read by your server with a bearer token for many people behind one address, so it has its own allowance of 600 per minute, apart from the general one. Read it once per sign-in and keep what you need; do not poll it.

A 429 on any of these means a person's sign-in fails. Watch X-RateLimit-Remaining on your own responses and treat a refusal as an alert, not a retry.

Wrong client secrets lock the client, not the address. A confidential client's failed authentications at the token endpoint are counted per client id, wherever they come from. After 10 in 10 minutes the token endpoint answers invalid_client (401) for that client until the window resets — a right secret during the lock is refused too, and a success does not reset the count. It is a 401 rather than a 429, with no Retry-After: a lock means something is guessing your secret, so rotate it rather than wait it out.

Three headers on every response

They are on successful responses too, so you can slow down before you are stopped rather than after.

The refusal

Over the limit, the API answers 429 with the ordinary error envelope, code RATE_LIMIT_EXCEEDED, and a Retry-After header in seconds. Wait that long; do not retry sooner.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "requestId": "…",
    "details": { "retryAfterSeconds": 42 }
  }
}