# Statuses and reasons

Every file has a `status` that says how far Ocost is with it. A file that wasn't read also has a `reason`. Branch on both.

## Statuses

| Status | Meaning | What to do |
| --- | --- | --- |
| `received` | Stored, not read yet. | Wait. |
| `reading` | Being read. | Wait. |
| `read` | Read. `documents` lists what it holds. | Read its documents. |
| `not_read` | Stored, but not read. | Look at `reason`. |
| `failed` | Ocost couldn't read it. | Look at `reason`. |

While no reading service answers, a file stays `reading`. Ocost tries again for up to a day.

## Reasons

| Reason | With | Meaning |
| --- | --- | --- |
| `limit` | `not_read` | The month's documents are used up. Ocost reads the file by itself on `renews_on`. |
| `model_off` | `not_read` | This business doesn't have PDFs and images read. E-invoices are still read. |
| `nothing_found` | `not_read` | The file holds no document. |
| `too_large` | `not_read` | Too many pages, or too large an image. |
| `damaged` | `failed` | Not a file Ocost can open. |
| `unavailable` | `failed` | No reading service answered for a day. Send the same bytes again to retry. |
| `failed` | `failed` | Anything else. |
| `other` | either | A reason this version of the API doesn't name yet. |

## An example

A file sent after the month's documents ran out:

```json
{
  "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
  "name": "invoice.pdf",
  "status": "not_read",
  "reason": "limit",
  "renews_on": "2026-12-01",
  "documents": []
}
```

Ocost reads it on 1 December, or sooner once the plan grows. Keep polling or [stay in sync](https://docs.ocost.io/en/sync.md), and it turns up as `read`.

## Long files

Ocost reads only the first pages of a long PDF. `pages` counts the file's pages, and `pages_read` says how many were read. `pages_read` is `null` when Ocost read all of them.