# 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.