Limits and errors

Your plan

Each document read counts once against your business's month (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.