Rate Limits

Overview

APIs often enforce rate limits to prevent abuse and ensure stability. This section explains how rate limits work, the relevant headers, and how to handle cases when the limit is exceeded. Rate limits are applied per client IP address over a one-minute window. The maximum number of requests allowed in that window may change, and the current value is returned in the x-ratelimit-limit header of every response, so your client should read it from there instead of hardcoding a value.

Rate limit Headers

Every successful response includes the following headers to help you manage your request quota:

Header	Description
`x-ratelimit-limit`	Maximum number of requests allowed per one-minute window
`x-ratelimit-remaining`	Number of requests remaining in the current window
`x-ratelimit-reset`	Number of seconds until the current window resets (maximum 60)

These values are indicative and may vary slightly between consecutive responses. Treat a 429 response and its retry-after header as the source of truth.

Example Headers

x-ratelimit-limit: 1000
x-ratelimit-remaining: 997
x-ratelimit-reset: 42

When the limit is reached

If you exceed the allowed number of requests, the API responds with HTTP 429 Too Many Requests and includes a retry-after header with the number of seconds to wait before making new requests.

Example Response

Headers:

x-ratelimit-limit: 1000
x-ratelimit-remaining: 0
x-ratelimit-reset: 45
retry-after: 45

Body:

{
  "code": "rate_limit_exceeded",
  "message": "Too many requests, retry in 45 seconds."
}

Use the code field to detect this error. The message text is intended for humans and may change.

Best practices for handling rate limits

Wait the number of seconds indicated by retry-after before retrying after a 429.
Implement exponential backoff with jitter for repeated 429 responses.
Spread bulk operations over time instead of sending them in bursts.
Cache responses when possible to reduce unnecessary requests.

Get Started

Guides

Data Models

Authentication

Corporations

Employees

Family Members

Limits

Consumption Reports

Payroll Cycles

Committed Expenses

Overview

Rate limit Headers

Example Headers

When the limit is reached

Example Response

Best practices for handling rate limits

​Overview

​Rate limit Headers

​Example Headers

​When the limit is reached

​Example Response

​Best practices for handling rate limits

Overview

Rate limit Headers

Example Headers

When the limit is reached

Example Response

Best practices for handling rate limits