[← API v2 Overview](https://motordesk.com/api-docs/v2/)

# Rate Limits

Requests are rate limited per business using a fixed window. Design syncs and pollers to stay within the budget and to back off when throttled.

## The Limit

Two budgets apply per business, both enforced independently:

- A short **burst budget** of **300 requests per 60-second window**.
- A **daily budget** of **10,000 requests per 24-hour window**.

Each window is fixed and the budgets are per business: all of a business's API keys share the same budget. Exhausting either budget returns `429` until that window resets.

## Headers

Every authenticated response carries the current budget state, so you can throttle proactively rather than waiting for a rejection:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Requests permitted in the current burst (60-second) window. |
| `X-RateLimit-Remaining` | Requests remaining in the current burst window. |
| `X-RateLimit-Reset` | Unix timestamp when the burst window resets and the budget refills. |
| `X-RateLimit-Limit-Day` | Requests permitted in the current daily (24-hour) window. |
| `X-RateLimit-Remaining-Day` | Requests remaining in the current daily window. |
| `X-RateLimit-Reset-Day` | Unix timestamp when the daily window resets and the budget refills. |

## When You Exceed It

Once either budget is exhausted the API responds `429` with the `rate_limited` error code and a `Retry-After` header (seconds until the exhausted window resets). The `Remaining` header for the exhausted window will be `0`.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1781560330
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 4173
X-RateLimit-Reset-Day: 1781603530

{
  "success": false,
  "error": { "code": "rate_limited", "message": "API rate limit exceeded. Please retry later." }
}
```

## Recommended Handling

- **Honour `Retry-After`** on a `429`: wait at least that long before retrying.
- **Watch `X-RateLimit-Remaining`** and slow down as it approaches zero rather than sprinting into a `429`.
- **Back off exponentially** on repeated `429`s, and add jitter so parallel workers don't retry in lockstep.
- **Prefer keyset pagination** (the `cursor` parameter) and `view=simple` / `fields=` to fetch more per request and reduce call volume.
- **Spread polling**: for lead/message sync, poll on an interval comfortably within the budget rather than tight-looping (see [polling guidance](https://motordesk.com/api-docs/v2/overview/#polling)).