Skip to content

Rate Limiting

Rate limits are enforced per authenticated user and per API scope. Exceeding the limit in one scope does not affect requests to other scopes.

Current API scopes:

  • phonebook
  • call-control

Rate limiting algorithm

Rate limits are enforced using a sliding window algorithm.

Requests are counted within the previous time window (for example, the last 60 seconds). Each request timestamp is tracked and older timestamps automatically expire as the window moves forward.

Example rule:

30 requests per 60 seconds

If a client sends 30 requests within 60 seconds, the next request will be rejected until the earliest request becomes older than 60 seconds.

Rate limit headers

The API exposes rate limit headers on every response, including successful responses. These headers are included on all responses, including successful requests and responses returning HTTP 429. These headers follow the RateLimit header specification (RFC 9442).

Headers returned:

  • RateLimit-Limit
  • RateLimit-Remaining
  • RateLimit-Reset
  • RateLimit-Policy

Explanation:

  • RateLimit-Limit
    Maximum number of requests allowed within the rate-limit window.
  • RateLimit-Remaining
    Number of requests remaining in the current window.
  • RateLimit-Reset
    Number of seconds until at least one request becomes available again.
  • RateLimit-Policy
    Describes the configured rate-limit rule.

Example:

RateLimit-Policy: 30;w=60

Meaning:

30 requests allowed per 60-second window

RateLimit-Policy describes the configured rule, while the other RateLimit-* headers describe the current quota state.

Successful response before rate limit

Example response:

HTTP 200 OK

RateLimit-Limit: 30
RateLimit-Remaining: 18
RateLimit-Reset: 42
RateLimit-Policy: 30;w=60

These headers allow clients to monitor quota usage and adjust request rates accordingly.

Rate limit exceeded response

Example headers:

HTTP 429 Too Many Requests

Retry-After: 23
RateLimit-Limit: 30
RateLimit-Remaining: 0
RateLimit-Reset: 23
RateLimit-Policy: 30;w=60

Example response body:

{
  "type": "client_error",
  "errors": [
    {
      "code": "throttled",
      "detail": "Request was throttled. Expected available in 23 second.",
      "attr": null
    }
  ]
}

Retry-After and RateLimit-Reset

Two headers indicate when new requests can be made.

Retry-After

  • Defined in the HTTP specification (RFC 9110)
  • Indicates when a client may retry a failed request

RateLimit-Reset

  • Defined by the RateLimit header specification (RFC 9442)
  • Indicates when rate-limit quota becomes available again

Important clarification:

RateLimit-Reset header describes quota state, while Retry-After indicates when the failed request may be retried.

In the current implementation both headers return the same value because a request becomes valid again exactly when quota becomes available within the sliding window.

Both headers are returned to ensure compatibility with existing HTTP clients while exposing standardized rate-limit telemetry.