# Rate limits and usage
How requests are counted against your plan, what the 429 response looks like, and the size limit on a single request.
<Warning>
**Forward-looking.** Rate limiting, usage caps, and the `402`, `403`, 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 for those, because none are in
effect. Request-size limits are the exception: they are enforced today, and
the limit is published below.
</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
Every plan caps how large a single input document may be: 5 MB on Free, 10 MB
on every other plan (see [Pricing](/pricing)). A request whose body exceeds
that limit is rejected with `413 Payload Too Large`, returning a
[problem+json](/docs/api/errors) body without processing it. Unlike a `429`, a
`413` will not succeed on retry: send a smaller file, or ask us to raise the
limit for your account if you regularly need more.
## 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 requests are counted against your plan, what the 429 response looks like, and the size limit on a single request.
Forward-looking. Rate limiting, usage caps, and the 402, 403, 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 for those, because none are in
effect. Request-size limits are the exception: they are enforced today, and
the limit is published below.
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.
Every plan caps how large a single input document may be: 5 MB on Free, 10 MB
on every other plan (see Pricing). A request whose body exceeds
that limit is rejected with 413 Payload Too Large, returning a
problem+json body without processing it. Unlike a 429, a
413 will not succeed on retry: send a smaller file, or ask us to raise the
limit for your account if you regularly need more.
