---
title: "Understanding rate limiting"
slug: "understanding-rate-limiting"
updated: 2026-08-10T06:00:06Z
published: 2026-08-10T06:00:06Z
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.

## How limits are applied

Each caller has two independent limits — buckets — per project, based on the HTTP method:

| Bucket | HTTP methods | Typical use |
| --- | --- | --- |
| Read | `GET`, `HEAD` | Fetching articles, listing users and readers, analytics |
| Write | `POST`, `PUT`, `PATCH`, `DELETE` | Creating, updating, publishing, deleting content |

Because the buckets are independent, heavy read traffic never exhausts your ability to write, and vice versa. Each bucket allows a maximum number of requests within a fixed time window; when the window elapses, the allowance resets.

Note

The exact limits depend on your Document360 plan. When no plan-specific limit is configured, each bucket defaults to 60 requests per 60-second window. Contact support if your integration needs a higher limit.

## 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 — 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. Because the limit is per project, project-less routes such as `GET /v3/projects` are not rate limited.