> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Rate limits

API v2 has two kinds of limit. A token bucket counts requests and units per minute. A concurrency limit counts the jobs that run at the same time. The [Limits](https://dash.cloudraker.com/limits) page of Dash shows your tier and the current use.

## Tiers

| Tier         | When                                             | Requests per minute | Units per minute | Concurrent jobs: parse / action / agent / inline |
| ------------ | ------------------------------------------------ | ------------------- | ---------------- | ------------------------------------------------ |
| `test`       | Test keys. Live keys before the first plan sync. | 60                  | 200              | 1 / 1 / 1 / 2                                    |
| `free`       | Free plans and trials                            | 120                 | 500              | 1 / 1 / 1 / 4                                    |
| `starter`    | Starter                                          | 600                 | 3000             | 5 / 5 / 5 / 10                                   |
| `pro`        | Pro                                              | 1200                | 10000            | 10 / 10 / 10 / 20                                |
| `enterprise` | Enterprise                                       | 3000                | 30000            | 10 / 10 / 25 / 50                                |

Live and test each have their own buckets and concurrency slots, so a test job never uses a live slot.

Units are the metered amounts of a job, for example pages. They are the values in `usage.units`.

Test keys always have the `test` tier limits, but their jobs use real paperwork credits.

A [key](/paperwork/v2/keys) with a rate cap, or a [trust](/paperwork/v2/oidc-trusts) with a requests limit, has its own requests bucket inside the organization limits.

## Headers

Every admitted or refused answer has these headers:

| Header                           | Meaning                                                |
| -------------------------------- | ------------------------------------------------------ |
| `x-ratelimit-limit-requests`     | The size of the requests bucket per minute.            |
| `x-ratelimit-remaining-requests` | The requests left now.                                 |
| `x-ratelimit-reset-requests`     | The time to a full bucket, for example `2s` or `1m0s`. |
| `x-ratelimit-limit-units`        | The size of the units bucket per minute.               |
| `x-ratelimit-remaining-units`    | The units left now.                                    |
| `x-ratelimit-reset-units`        | The time to a full bucket.                             |
| `retry-after`                    | On a `429`: the seconds to wait, 1 or more.            |

The units headers are absent when the units limit does not apply. A `404 tenant_not_found` has no rate-limit headers.

## Refusals

| Status | Code                  | Cause                                  | Action                              |
| ------ | --------------------- | -------------------------------------- | ----------------------------------- |
| `429`  | `rate_limit_exceeded` | The requests or units bucket is empty. | Wait for the time in `retry-after`. |
| `429`  | `concurrency_limited` | The class of the job has no free slot. | Wait for a running job to finish.   |
| `402`  | `credits_exhausted`   | The organization has no credits.       | Add credits in Dash.                |

A refused request does not use rate budget. A job in `needs_input` holds no slot.

A units bucket needs a positive balance to admit a job. The job takes its real units from the bucket when it ends.

## Concurrency classes

| Class    | Capabilities                                             |
| -------- | -------------------------------------------------------- |
| `parse`  | `parse`, `transcribe`                                    |
| `action` | `extract`, `classify`, `split`, `fill`, `redact`, `sign` |
| `agent`  | `agents`                                                 |
| `inline` | `generate`, `convert`, `redline`                         |

## How the limits work

The buckets live in memory, one per organization and environment. A deploy can refill a bucket. Do not treat a refill as a higher limit.

Your plan sets the tier. To ask for higher limits, contact CloudRaker from the [Limits](https://dash.cloudraker.com/limits) page.