Builder's guide · Appendix B

Error codes you will meet first

Code	HTTP	Meaning and what the screen should do
`VALIDATION_ERROR`	400/422	One or more fields are wrong; mark each one from `details[].field`
`AMOUNT_INVALID`	422	An amount isn't a two-decimal string
`JOURNAL_UNBALANCED`	422	Debits don't equal credits; show both totals
`PERIOD_CLOSED`	422	The date falls in a closed period; suggest a date in an open one
`CONTROL_ACCOUNT_RESTRICTED`	422	That account is fed by a subledger; use the right document (bank, invoice, bill)
`INSUFFICIENT_FIFO_QUANTITY`	422	Not enough stock at that location to issue
`DOCUMENT_NOT_DRAFT`	409	The document was already posted; refresh and show its current state
`DOCUMENT_NUMBER_ASSIGNED`	422	A number series assigns this number; don't send one
`IDEMPOTENCY_KEY_MISSING`	400	A write without a key: a bug in your client
`IDEMPOTENCY_KEY_REUSED`	409	Same key, different body: a bug in your key handling
`IDEMPOTENCY_KEY_IN_PROGRESS`	409	The first attempt is still running; wait and retry with the same key
`OPERATION_NOT_PERMITTED`	403	The writer's role doesn't allow this route
`COMPANY_NOT_IN_SCOPE`	403	The writer isn't scoped to that company; an administrator widens the scope
`INTERNAL_ERROR`	500	Unexpected; safe to retry with the same idempotency key

Codes are permanent: once published, a code is never renamed or reused. The full registry is section C3 of docs/api-conventions.md.