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

StatusMeaningWhat to do
receivedStored, not read yet.Wait.
readingBeing read.Wait.
readRead. documents lists what it holds.Read its documents.
not_readStored, but not read.Look at reason.
failedOcost couldn't read it.Look at reason.
needs_companyRead, 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

ReasonWithMeaning
limitnot_readThe month's documents are used up. Ocost reads the file by itself on renews_on.
model_offnot_readThis business doesn't have PDFs and images read. E-invoices are still read. Once it does, send the same bytes again.
nothing_foundnot_readThe file holds no document.
too_largenot_readToo many pages, or too large an image.
damagedfailedNot a file Ocost can open.
unavailablefailedNo reading service answered for a day. Send the same bytes again to retry.
failedfailedReading failed or was refused. Ocost tries a failed read again 10 and 60 minutes later. Send the same bytes again to retry sooner.
othereitherA 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:

ReasonRead again
unavailableEvery time you send it.
failedEvery time you send it, from a minute after it failed. A file the model refused is read again once.
model_offOnce 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, 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