# Limits and errors

## Your plan

Each document read counts once against your business's month ([Settings › Plan](/settings/plan)); resent bytes and searches count nothing. `X-Ocost-Documents-Left` on each `POST /public/v1/files` answer says what is left.

At the limit a file is still stored, `not_read` with `reason: "limit"` and `renews_on`, and read by itself once the month renews or the plan grows.

## Rate limits

| Per key, per minute | Limit |
| --- | --- |
| `documents:write` (send, delete) | 120 calls |
| `documents:read` (files, documents, bytes, list) | 600 calls |
| `search:read` | 60 searches |

Past one: `429 urn:ocost:key:rate` with `Retry-After` in seconds. From one address, 30 wrong keys a minute get `401`, more get `429`.

Per address, all keys together: 50 requests a second (bursts to 200), 100 open at once; past that, a plain-text `429` with `Retry-After`. Spread a batch over its minute.

## Sizes

- A file: up to 25 MB, refused before it is read (`413 urn:ocost:file:too_large`).
- A long PDF: only its first pages are read; `pages_read` says how many.
- A search: `q` up to 200 characters, `limit` up to 50, `offset` up to 250.

## Errors

RFC 9457 problems, `Content-Type: application/problem+json`. Branch on `status` and `type`; `detail` is English for your logs and may change.

```json
{
  "type": "urn:ocost:key:scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the scope documents:write.",
  "instance": "/public/v1/files"
}
```

| Type | Status | Meaning |
| --- | --- | --- |
| `urn:ocost:key:invalid` | 401 | No key, or a wrong, revoked or expired one. |
| `urn:ocost:key:scope` | 403 | The key lacks the scope. |
| `urn:ocost:key:rate` | 429 | Too many calls; wait `Retry-After`. |
| `urn:ocost:file:too_large` | 413 | Over 25 MB. |
| `urn:ocost:file:format` | 415 | A format Ocost doesn't read. |
| `urn:ocost:file:reading` | 409 | Being read; delete it later. |
| `urn:ocost:file:kept` | 409 | The same bytes are kept where the key doesn't see them. |
| `urn:ocost:file:linked` | 409 | Ocost still needs it (paid, matched, booked, an open question, a project's); delete it in Ocost once nothing does. |
| `about:blank` | 404 | No such file or document, or another business's. |
| `about:blank` | 422 | Invalid fields, each in `errors[]` with its `loc`. |
| `about:blank` | 503 | Try again shortly. |

## Retrying

- `429`, `5xx`: after `Retry-After`, or with growing pauses (1, 2, 4, … seconds, at most a minute).
- Resending a file is safe: the same bytes are the same file. So is deleting again (`404`).
- `401`: stop and tell a person; the key needs replacing.
- Other `4xx`: don't retry as is.

## Data

Ocost runs in the EU. Originals, readings and the search index stay until you delete the file (`DELETE /public/v1/files/{file_id}`) or your business is deleted. Documents never train a model.