Statuses and reasons

View as Markdown

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, 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.