Rate Limiting

API requests are rate-limited to ensure fair usage and to protect the stability of the service for all tenants.

Rate limit headers are included in all responses:

• X-RateLimit-Limit: The maximum number of requests allowed in the current window.

• X-RateLimit-Remaining: The number of requests remaining in the current window.

• X-RateLimit-Reset: The Unix timestamp (in seconds) at which the current rate limit window resets.

When you exceed the allowed rate, the API may return:

• 429 Too Many Requests – Your client has sent too many requests in a short period.

• In some cases, a `Retry-After` header that indicates how many seconds to wait before retrying.

Recommended client behaviour (Do's)

• Do implement exponential backoff and jitter when you receive 429 or 5xx responses, instead of retrying immediately.

• Do inspect `X-RateLimit-Remaining` and proactively slow down when you are close to the limit.

• Do respect `X-RateLimit-Reset` / `Retry-After` and pause sending non-critical requests until the window resets.

• Do batch operations where possible (for example, send a smaller number of larger requests instead of many tiny ones).

• Do separate critical and non-critical traffic so that non-essential features can be throttled first.

• Do monitor rate limit headers in production to understand real usage patterns and avoid unexpected throttling.

Behaviours to avoid (Don'ts)

• Don't run tight retry loops that ignore 429 responses or Retry-After headers.

• Don't fire large, sudden bursts of requests (for example, replaying months of data without any throttling).

• Don't share a single set of credentials across unrelated systems that cannot coordinate their rate usage.

• Don't ignore X-RateLimit-Remaining; continuing to send traffic at full speed after it reaches zero will result in more 429 errors.

• Don't treat rate limit errors as fatal; they usually indicate temporary throttling and should be handled with controlled retries.