---
title: "Understanding rate limiting"
slug: "understanding-rate-limiting"
description: "Learn about v3 Customer API's rate limiting, ensuring fair use and efficient traffic management with independent request buckets for read and write operations."
tags: ["Rate Limiting", "API Key", "Request Buckets"]
updated: 2026-09-30T04:33:07Z
published: 2026-09-30T04:33:07Z
canonical: "apidocs.document360.com/understanding-rate-limiting"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.document360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding rate limiting

The v3 Customer API applies rate limiting to protect the service and ensure fair use. Limits are enforced per API key per project, so one integration's traffic never consumes another's allowance.

## Limits by plan

API rate limits are applied per API key and are measured in requests per minute. API access is available on the Business, Enterprise, and Trial plans. The standard limits for each plan are:

| Plan | Read (requests per minute) | Write (requests per minute) |
| --- | --- | --- |
| Business | 120 | 60 |
| Enterprise | 200 | 100 |
| Trial | 200 | 100 |

Note

These are the standard limits. Your project may have different limits based on your commercial arrangement. To see the limit that applies to a request, check the `X-RateLimit-Limit` header in the response.

## Rate-limit response headers

Every successful (2xx) response includes headers describing your current allowance:

| Header | Description |
| --- | --- |
| `X-RateLimit-Limit` | The maximum number of requests allowed in the current window for this request's bucket. |
| `X-RateLimit-Remaining` | The number of requests remaining in the current window for that bucket. |

When you exceed a limit, the response adds two more headers:

| Header | Description |
| --- | --- |
| `X-RateLimit-Reset` | Seconds until the current window resets and requests are allowed again. |
| `Retry-After` | Seconds to wait before retrying; matches `X-RateLimit-Reset`. |

## When a limit is exceeded

If you exceed a bucket's limit, the API responds with `429 Too Many Requests` and an RFC 7807 `problem+json` body. The response sets `X-RateLimit-Remaining` to `0` and includes `Retry-After`.

```
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42
Retry-After: 42

{
  "type": "https://apidocs.document360.io/apidocs/errors/too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
  "trace_id": "req_abc123def456",
  "errors": [
    { "code": "TOO_MANY_REQUESTS", "message": "Rate limit exceeded. Retry after the duration specified in the Retry-After header." }
  ]
}
```

## Best practices

- Honour the `Retry-After` header: wait the specified number of seconds before retrying.
- Use exponential backoff with jitter for repeated `429` responses instead of retrying immediately.
- Watch `X-RateLimit-Remaining` and slow down as it approaches `0`, rather than waiting for a `429`.
- Spread bulk work over time, and prefer the bulk endpoints (up to 100 items per request) to reduce the number of calls.
- Separate read-heavy and write-heavy workloads where possible, since they draw on different buckets.

Tip

Rate limiting applies only to the v3 API and is keyed on your API key and project. CORS preflight (`OPTIONS`) requests are never rate limited.

## Related

- [Check email availability](/check-email-availability.md)
- [List users](/list-users.md)
- [List projects](/list-projects.md)