Rate limits

All v1 endpoints

Each authenticated caller (a service client, a device or a user) may send up to 120 requests per minute and 3,000 requests per hour across all /api/v1/* endpoints together.

• Each service client and each device has its own count. Devices of a tenant don't share a count with each other or with the tenant's service clients.
• Refused calls count too. So do calls refused for a missing scope (from a service client, a user or a device) or because the endpoint doesn't accept their kind of caller. Calls without valid credentials are refused before the limit is checked, and so are device calls with a reused DPoP proof, from a disabled device, or from a suspended or inactive organization; those don't count.
• Over the limit the API answers 429 Too Many Requests with a Retry-After header, in the same shape as the pass verification response below, plus "limit": "client". It has no livemode: the limit is checked before the endpoint runs.

Pass verification

Pass verifications have extra limits: POST /api/v1/verifications with "method": "pass". Manual and eID verifications have only the per-client limit above.

• These four limits and the per-client limit all apply at once; a call is refused when any of them is exceeded.
• The windows slide: the count covers the last minute or hour, not a calendar minute or hour.
• Refused calls count too. A client that keeps retrying while limited stays limited, so wait for Retry-After before trying again.
• Malformed and unknown Pass Tokens count as well: the limit is checked before the token is read.
• Which "device" is counted. For a device calling with DPoP, the device itself. For a service client, the deviceId in the request body (an api-origin device created with POST /api/v1/devices), or the service client as a whole when no deviceId is given. A service client that serves several tills can send each till's deviceId so they are limited separately; they still share the tenant limit.
• The limits are enforced centrally, so they hold no matter which server handles the request.

The 429 response

A refused pass verification returns 429 Too Many Requests with a Retry-After header (seconds) and an RFC 7807 Problem Details body. retryAfterSeconds repeats the header value. No transaction is recorded for a refused call.

{
  "type": "https://api.aldursvottun.is/errors/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded, retry after 45 second(s)",
  "reason": "rate_limited",
  "retryAfterSeconds": 45
}

Token endpoint

POST /api/oauth/token with grant_type=client_credentials allows 30 requests per minute per client_id, failed ones included. The count is kept by each API server separately, so treat 30 per minute as the most you can rely on. Device grants (device_code and refresh_token) are not limited. Over the limit the endpoint answers in the OAuth error format, not Problem Details:

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

{"error":"slow_down"}

Access tokens last 5 minutes, so an integration needs only one token request every few minutes. Cache the token and reuse it until it expires. See Authentication.

Rate limit headers

The API does not send X-RateLimit-* headers. The only signal is the 429 response and its Retry-After header.

Best practices

• On a 429, wait at least Retry-After seconds before the next attempt. For pass verification, a retry sent sooner is counted and extends the wait.
• Reuse access tokens until they expire.
• Don't retry a pass verification automatically after a fail result; a Pass Token can be used only once.
• Contact support if you need higher limits for your use case.