# Rate limits

API v3 enforces rate limits at the API gateway, per OAuth 2.0 client. Requests are counted against the `client_id` of the access token obtained with the client credentials grant. All tokens issued to the same `client_id` share one allowance, regardless of source IP address, number of servers or number of tokens. Different clients never share an allowance.

| Limit | Value |
|  --- | --- |
| Sustained rate | 15 requests per second |
| Burst capacity | 15 requests |
| Daily quota | 120,000 requests per UTC day (00:00:00 to 23:59:59 UTC) |


Every authenticated request counts towards the limits, whatever the endpoint, HTTP method or response status. CORS preflight (`OPTIONS`) requests are not counted.

## How the per-second limit is applied

The rate and burst limits use a token bucket. The bucket holds up to 15 tokens and refills at 15 tokens per second. Each request takes one token, and a request that arrives when the bucket is empty is rejected with `429`.

- After a quiet period, up to 15 requests can be sent at the same moment.
- Sustained throughput cannot go above 15 requests per second.
- If 30 requests are sent at the same moment, about 15 succeed and the rest get `429`.


Limits are applied on a best-effort basis and may briefly allow slightly more traffic. Design your integration for the published values.

## Error responses

Errors from the gateway have `Content-Type: application/json` and a body with a single `message` field. Both limit errors use status `429`, so use `message` to tell them apart.

| Status | Body | Cause | Retry? |
|  --- | --- | --- | --- |
| 429 | `{"message":"Too Many Requests"}` | Rate or burst limit exceeded | Yes, with exponential backoff |
| 429 | `{"message":"Limit Exceeded"}` | Daily quota used up | No, not before 00:00 UTC |
| 401 | `{"message":"Unauthorized"}` | Missing, malformed, expired or invalid access token | Only after getting a new token |
| 403 | `{"message":"User is not authorized to access this resource with an explicit deny"}` | Token has neither the `api/read` nor the `api/write` scope, or the client is not enabled for API v3 | No, contact support |
| 500 | `{"message": null}` | Temporary error while validating the request | Yes, with exponential backoff |


Responses do not include a `Retry-After` header or `X-RateLimit-*` headers. A request rejected with `429` is stopped at the gateway and never reaches the application, so it has no side effects. Retrying it is safe, including for `POST`, `PUT` and `DELETE`.

## Retrying

Retry `429 Too Many Requests` and `500` responses using exponential backoff with full jitter:

- `delay = random(0, min(30 s, 1 s × 2^attempt))`
- maximum of 5 retries
- do not retry `429 Limit Exceeded`


Example (JavaScript):

```javascript
async function callApi(url, options, maxRetries = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429 && res.status !== 500) return res;
    const body = await res.clone().json().catch(() => ({}));
    if (body.message === 'Limit Exceeded' || attempt >= maxRetries) return res;
    const delayMs = Math.random() * Math.min(30000, 1000 * 2 ** attempt);
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
}
```

## Best practices

- Pace requests on the client side to stay under 15 per second, and keep the number of requests in flight low.
- Request an access token once and reuse it until it is close to expiry (see `expires_in` in the token response). Do not request a new token for every call.
- When paging, stop when a page is empty or has fewer items than the requested size. Set an upper bound on the number of pages a job can request.
- Cache data that changes rarely, such as reference and configuration data, instead of fetching it on every run.
- Stagger scheduled jobs rather than starting them all at the same time.


If your integration needs higher limits, contact [support@resharmonics.com](mailto:support@resharmonics.com) with your expected peak requests per second and daily volume.