# Statuses and reasons
> A file's statuses and the reasons it wasn't read, and what to do for each.
>
> Before: [Send a file and read it](https://ocost.io/docs/en/files.md)

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`. |
| `needs_company` | Read, but which company of the group it belongs to is open. `candidates` lists them. | `PATCH` it with the `business_id`, or wait. See [Company groups](https://ocost.io/docs/en/groups.md). |

> [!NOTE]
> While no reading service answers, a file stays `reading`. Ocost tries again for up to a day.

## Waiting for its company

A file of a group's key waits as `needs_company` when its document names several companies of the group, or another one by its name alone. Each of its `candidates` says `why`: an identifier the document prints, `name` or `home`.

In Ocost, the owner or the accountant answers under Today › Assign, or in Files › Not yet assigned. Ocost suggests the first candidate, unless it is `home`. The file then moves to that company and is read there. A file mailed to the group's own address waits in the group's inbox until its company is clear. No key reaches that inbox. [Company groups](https://ocost.io/docs/en/groups.md#assign-a-waiting-file) shows the same answer with `PATCH`.

## 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. Once it does, send the same bytes again. |
| `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` | Reading failed or was refused. Ocost tries a failed read again 10 and 60 minutes later. Send the same bytes again to retry sooner. |
| `other` | either | A reason this version of the API doesn't name yet. |

## Sending it again

Sending the same bytes again answers the same file, with the same `id`. Ocost counts it once. For three reasons it reads the file again from the bytes it keeps, and the file turns `reading`:

| Reason | Read again |
| --- | --- |
| `unavailable` | Every time you send it. |
| `failed` | Every time you send it, from a minute after it failed. A file the model refused is read again once. |
| `model_off` | Once the business has a reading model. |

For any other reason, sending it again changes nothing. Don't delete a file to send it again: a new file is counted again. A file once read keeps its reading when Ocost's reader improves. Only Read again in Files reads it anew.

## 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://ocost.io/docs/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.

## See also

- [Send a file and read it](https://ocost.io/docs/en/files.md): Send a file, send it again safely, wait until it is read, read its documents, get the original, delete it.
- [Limits and errors](https://ocost.io/docs/en/limits.md): The plan's documents a month, rate limits, sizes, RFC 9457 errors, retrying, and where the data is kept.
- [Company groups](https://ocost.io/docs/en/groups.md): Company groups: which companies a key reaches, the Ocost-Business header, routing by the document’s identifiers, needs_company, and files across the group.
