# Rate limits and usage
How usage is metered per plan, the 429 rate-limit contract, and request-size limits — forward-looking where thresholds aren't enforced yet.
<Warning>
**Forward-looking.** Rate limiting, usage caps, and the `402`, `403`, `413`,
and `429` responses are part of the API contract but are **not enforced yet**.
This page describes how they behave so you can build a client that is ready for
them. No numeric thresholds are published here, because none are in effect.
</Warning>
PDF Blocks is built to fail gracefully under load and to keep your usage visible.
This page covers how usage is metered, how rate limiting surfaces, and how to
size your requests.
## How usage is metered
Usage is metered per plan and tracked in your
[dashboard](https://dashboard.pdfblocks.com). The dashboard is the source of
truth for what you've consumed against your plan — both the number of documents
processed and the number of requests made. Check it to monitor consumption and to
see how close you are to your plan's allowance.
Because the API is stateless, each request is metered on its own; there are no
sessions or batches to reconcile. A multi-document action such as a split still
counts as a single request.
## Rate limits and the 429 response
When rate limiting is enforced, requests that exceed your plan's allowance are
answered with `429 Too Many Requests` and a
[problem+json](/docs/api/errors) body. A `429` is transient — the same request
will succeed once you slow down.
Build clients to handle it from day one:
- **Back off exponentially.** On a `429`, wait before retrying and increase the
delay on each successive `429` (for example, doubling it) instead of retrying
immediately in a tight loop.
- **Respect `Retry-After`.** When the response carries a `Retry-After` header,
wait at least that long before retrying rather than using your own delay.
- **Add jitter.** Randomize the backoff slightly so parallel workers don't retry
in lockstep.
- **Cap retries.** Give up after a sensible number of attempts and surface the
failure rather than retrying forever.
The same backoff strategy applies to the rare `5xx` server error.
## Request-size limits
Very large uploads may be rejected with `413 Payload Too Large`. When this limit
is enforced, a request whose body exceeds the accepted size returns a
[problem+json](/docs/api/errors) body and is not processed. Unlike a `429`, a
`413` will not succeed on retry — you must send a smaller file.
For strategies on streaming uploads and downloads, timeouts, and processing big
documents, see
[Working with large files](/docs/api/working-with-large-files).
## Billing-related responses
Two more reserved codes relate to your account rather than the individual
request:
- **`402 Payment Required`** — a billing or quota condition on your plan. Resolve
it from the [dashboard](https://dashboard.pdfblocks.com).
- **`403 Forbidden`** — your key is valid but not permitted to use the requested
resource.
Both appear in the [Errors](/docs/api/errors) catalog alongside the full response
shape.
How usage is metered per plan, the 429 rate-limit contract, and request-size limits — forward-looking where thresholds aren't enforced yet.
Forward-looking. Rate limiting, usage caps, and the 402, 403, 413,
and 429 responses are part of the API contract but are not enforced yet.
This page describes how they behave so you can build a client that is ready for
them. No numeric thresholds are published here, because none are in effect.
PDF Blocks is built to fail gracefully under load and to keep your usage visible.
This page covers how usage is metered, how rate limiting surfaces, and how to
size your requests.
Usage is metered per plan and tracked in your
dashboard. The dashboard is the source of
truth for what you’ve consumed against your plan — both the number of documents
processed and the number of requests made. Check it to monitor consumption and to
see how close you are to your plan’s allowance.
Because the API is stateless, each request is metered on its own; there are no
sessions or batches to reconcile. A multi-document action such as a split still
counts as a single request.
When rate limiting is enforced, requests that exceed your plan’s allowance are
answered with 429 Too Many Requests and a
problem+json body. A 429 is transient — the same request
will succeed once you slow down.
Build clients to handle it from day one:
Back off exponentially. On a 429, wait before retrying and increase the
delay on each successive 429 (for example, doubling it) instead of retrying
immediately in a tight loop.
Respect Retry-After. When the response carries a Retry-After header,
wait at least that long before retrying rather than using your own delay.
Add jitter. Randomize the backoff slightly so parallel workers don’t retry
in lockstep.
Cap retries. Give up after a sensible number of attempts and surface the
failure rather than retrying forever.
The same backoff strategy applies to the rare 5xx server error.
Very large uploads may be rejected with 413 Payload Too Large. When this limit
is enforced, a request whose body exceeds the accepted size returns a
problem+json body and is not processed. Unlike a 429, a
413 will not succeed on retry — you must send a smaller file.
For strategies on streaming uploads and downloads, timeouts, and processing big
documents, see
Working with large files.
