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. |
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. |
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 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:
{
"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, 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.