Skip to content

Rate Limiting

Our APIs enforce token-bucket rate limits to ensure fair use and predictable performance for all clients. This page explains how limits are applied, how to read rate-limit headers, and what your client should do when throttled.

Overview

Each request consumes tokens from a per-client “bucket.”

  • Every client starts with a full bucket (Token Limit tokens).
  • Tokens replenish periodically by a fixed amount (Tokens Per Period) after each Replenishment Period.
  • When no tokens are left, requests are rejected with HTTP 429 Too Many Requests.
  • Tokens refill automatically as time passes.

Partitioning

Rate limits are partitioned per caller to isolate and avoid interference between clients.

The partition key used is:

  • If the caller is authenticated:
    The username, or GUID of the signed-in user if a username is not available.

  • If the caller is anonymous:
    The IP address of the HTTP request.

Each partition maintains its own token bucket and counters. The partition key is available in responses from our APIs.

Example:

pk=:ZjI5MjM3Y2EtNjBkOC00ODczLWFhNGQtM2EyNGI5YzY0NTk4:
pkhint="f29237ca-60d8-4873-aa4d-3a24b9c64598"

Here pk is the base64-encoded (opaque) version of the partition key, and pkhint is a readable hint (user ID or IP address).

  • Please note that pkhint is a non-standard parameter provided to simplify diagnostics and may not always be provided in responses.
  • Both parameters must be treated as opaque to the client and used solely for diagnostics and logging.

Response Headers

Responses include modern IETF RateLimit headers. We provide rate limit headers in responses to failed rate-limited requests, but also on successful requests (when a rate limit policy applies).

Header Example Meaning
RateLimit-Policy "api"; q=5; w=10; pk=:MTcyLjE3LjAuMQ:; pkhint="172.17.0.1" The policy that applies to the request. Policy name is "api", which allows 5 requests per 10 s window. pk identifies your rate-limit bucket.
RateLimit "api"; r=4; t=3 Your client's current rate limit state. Here, 4 requests remain, and the window resets in 3 s (new tokens are added automatically after this time). Please note that this header is not always provided, e.g., during maintenance.
Retry-After 10 Wait 10 s before retrying. Instructs the client to wait the specified number of seconds. Present only on 429 Too Many Requests responses.

Typical Flow

Typical flow of a request:

  1. Start: You have 5 tokens available (q=5).
  2. Make a request: Remaining tokens (r) decrease.
  3. When r=0: The next request returns 429 Too Many Requests.
  4. After t seconds: The bucket refills automatically.

Example response:

RateLimit-Policy: "api"; q=5; w=10
RateLimit: "api"; r=4; t=3

→ Meaning: The policy allows 5 tokens (q) and has a 10 second window (w). You've used 1 of 5 requests; the bucket refills in 3 seconds (t).

Multiple Rate Limit Policies

If multiple rate limit policies apply to a request (e.g., a generic API policy and a more specific endpoint policy), all applicable policies are enforced. The response headers will include all active policies as comma-separated values.

Example response with multiple policies:

RateLimit: "auth-introspection"; r=29; t=10, "api-actors"; r=4; t=10
RateLimit-Policy: "auth-introspection"; q=30; w=10; pk=:MTAuMTAwLjAuNA:; pkhint="10.100.0.4", "api-actors"; q=5; w=10; pk=:bW9tZnJtYQ:; pkhint="momfrma"

In this example:

  • The auth-introspection policy allows 30 requests per 10 seconds, with 29 remaining.
  • The api-actors policy allows 5 requests per 10 seconds, with 4 remaining.
  • Both policies are evaluated independently; a request is rejected (429) if any policy's token bucket is empty.

Your client should monitor all policies and respect the most restrictive limit.

When You Hit the Limit

Example response when the limit is reached:

HTTP/1.1 429 Too Many Requests
RateLimit: "api"; r=0; t=7
RateLimit-Policy: "api"; q=5; w=10; pk=:MjU3ZGY5ZWEtOTdiZS00YjQ5LTg4MzUtMzcwZjZkYjQzNWIy:; pkhint="257df9ea-97be-4b49-8835-370f6db435b2" 
Retry-After: 7

Your client should pause requests for at least Retry-After seconds before retrying.

Best Practices for Clients

  • Respect Retry-After: Always back off when receiving 429.
  • Spread requests: Avoid bursts; pace requests within the window.
  • Use the headers: Adjust concurrency based on r and t.
  • If a RateLimit-Policy header is not included in the response, the API endpoint does not yet support rate limiting but may do so in the future.
  • Contact us if you hit a limit that seems unreasonable; we are here to help. Please include the relevant RateLimit headers in your support request.

Generic rate limits

Rate limits (limit, window, and policy name) are subject to change and may vary in real time based on system load and other considerations. Always use the RateLimit headers to determine the current active rate-limiting policy and state.

This is a starting point with typical limits:

Policy name Path Typical Limit Window Notes
api /api 30 10 s Base limit for REST endpoints.
graphql /api/graphql 40 10 s Base limit for GraphQL queries and mutations.
graphql-ws /api/graphql 3 10 s GraphQL WebSocket connection attempts. Counts each connect attempt; this is not a limit for the number of concurrently active connections.

The Policy name (e.g., api) appears in the RateLimit header. The most specific policy (by path, then predicate) applies to the request.

Service-specific rate limits

These are typical limits for the Login Service APIs:

Policy name Path Typical Limit Window Notes
api-auth-oauth /api/auth/oauth2 5 10 s OAuth APIs base policy (e.g., the token endpoint).
api-auth-oauth-clientauthenticated /api/auth/oauth2 100 10 s OAuth APIs policy with a higher rate that applies to authenticated clients (apps). This rate does not apply to the more specific paths listed below such as /api/auth/oauth2/authorize.
api-auth-oauth-authorize /api/auth/oauth2/authorize 5 10 s OAuth standard endpoint used to start an authorization front-end flow.
api-auth-oauth-userinfo /api/auth/oauth2/userinfo 5 10 s OAuth user-info standard endpoint. Please use /api/auth/oauth2/introspect, which uses client authentication, if you need a higher rate.
api-auth-oauth-end-session /api/auth/oauth2/end_session 2 10 s OAuth sign-out front-end flow.
api-actors /api/actors 5 10 s User information.
api-application /api/application 5 10 s Application configuration.
api-directory /api/directory 5 10 s Directory services.
api-sessions /api/sessions 5 10 s Session information.
discovery-openid /.well-known/openid-configuration 5 10 s Discovery with OpenID/OAuth metadata.
discovery-openid-keys /api/auth/oauth2/keys 5 10 s Discovery with OpenID/OAuth keys.
discovery-wsfederation /federationmetadata 5 10 s Discovery with WS-Federation metadata.