Skip to content

Rate Limits

Rate limits protect service reliability and are applied per API key.

Current enforced limits

The current implementation enforces these limits:

Key type Limit Window model
Standard partner API key (X-API-Key) 60 requests per 60 seconds Sliding window
Admin API key (X-Admin-API-Key) 300 requests per 60 seconds Sliding window

Important behavior:

  • Limits are tracked per key, not per IP address.
  • The server uses a sliding 60-second window, not a fixed calendar-minute reset.
  • A burst can therefore be accepted or rejected depending on how many requests the same key made during the immediately preceding 60 seconds.
  • Rate limiting is currently implemented in memory, so counters are runtime-local and not described as a distributed global quota.

Response headers

Successful requests include rate-limit headers:

  • X-RateLimit-Limit: maximum requests allowed for the current key type
  • X-RateLimit-Remaining: remaining requests in the current sliding window
  • X-RateLimit-Reset: Unix timestamp indicating when the server expects the window to clear

If the limit is exceeded, the API responds with:

  • HTTP 429
  • Retry-After header
  • error.code = RATE_LIMITED
  • error.details.retryAfter in the JSON body

Clients should prefer the returned Retry-After value over hard-coded retry timing.

  • Use a token bucket or queue in your API client.
  • Respect 429 responses with exponential backoff and jitter.
  • Avoid synchronized retries from multiple workers.
  • Share rate-limit state across workers if you fan out requests behind one API key.

What happens on 429

When a key is over limit, the request is rejected immediately and is not processed further.

Your client should:

  1. Stop sending more requests on the affected key.
  2. Wait for the Retry-After duration.
  3. Resume gradually instead of releasing a full retry burst at once.

Backoff example

Use an exponential strategy such as:

  • attempt 1: 500 ms
  • attempt 2: 1000 ms
  • attempt 3: 2000 ms
  • attempt 4: 4000 ms (cap)

Operational guidance

  • Track request volume and 429 rate per key.
  • Log X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After when present.
  • Alert if a single integration key spends sustained time near 0 remaining requests.
  • Request a limit review before major traffic events.