code is stable and snake_case — branch on it, not on the message. message is
human-readable and safe to log. No stack trace is ever returned.
General
422
Body or parameter failing schema validation; message is
field: reason.400
Unknown value in a list filter (also unknown
language on reference lists,
unknown format on file download).422
Query parameter that does not apply to the targeted resource (e.g.
?ignore_duplicate on a contact).422
Read-only field in a
PATCH — bic/reference of a non-manual bank account,
code/category/sequence_scope of a journal, type/journal_id of a
document — or a field that does not exist for the relation’s type.404
Unknown route or unknown UUID (including a UUID of another company).
500
Unexpected server error, logged on our side. Retry later; if it persists, contact
support with the
X-Request-ID from the response header — it lets us pull that
request’s trace straight away and speeds up handling (see
Conventions).Authentication
400
Missing credential field on
/auth/token.401
Unknown
client_id or wrong client_secret.401
Unknown, already-used or revoked
refresh_token.401
The client has been deactivated.
401
Missing, malformed or expired
access_token.403
The
access_token lacks the required permission.429
Too many failed authentications on this
client_id.Documents
422
relation_id unknown, belonging to another company, or with no address.422
Journal unknown, inactive, of another company, or of the wrong category for the
document type.
422
No
journal_id given and the company has no default journal for the category.422
Delivery location unknown or belonging to another relation than the document’s.
422
Document total negative.
422
Declared
paid_amount above the document total.422
Document-level discount/charge on lines totalling 0, or a VAT rate whose lines
total a negative amount.
422
Date outside the bracket of the neighbouring numbered documents, or outside the
numbering window.
422
Stored lines that cannot be reused for a recompute — send the full
lines array
instead.422
Creating a purchase document while self-billing is not enabled for the company.
422
Sending a document type Peppol does not transport (e.g. a proforma). As a
409:
sending a received document.422
The send workflow could not be started. With
?send_peppol=true the document
was created — the message gives its id; recover with
POST /documents/{id}/send, never a second creation.409
Peppol send on a document already sent — only a failed send (
peppol_status
failed or rejected) can be retried.409
Attachment filename already present on the document.
409
PATCH on a document already sent to the customer, already transmitted to
accounting, or received.409
DELETE on a document that is not the last of its sequence, already sent,
transmitted, or received.409
DELETE on a document linked to a reconciliation, an invoiced timesheet line or
a payment intent.413 (file too big) and
415 (extension not allowed).
Relations
409
Company whose
vat, identifier or electronic_address already exists —
bypass with ?ignore_duplicate=true; the message gives the existing id.422
Address without
country_code, or street_number without street.409
DELETE on a relation still referenced (document, subscription, project,
timesheet line, accounting match…). The message says what blocks.Delivery locations
422
Address without
country_code, or street_number without street — the same
rules as a relation’s address.422
identifier / identifier_scheme pair half-filled.422
On a document: location unknown or belonging to another relation than the
document’s.
409
DELETE on a delivery location a document is delivered to.Bank accounts
409
Account with the same
reference (IBAN) already exists.422
Demoting the default bank account without promoting another.
Journals
409
Journal
code already used in the company.422
Default journal created or left inactive, or demoting the last default of a
category.
422
bank_account_id matching no account of the company.Brandings
422
Demoting the default branding — promote another instead.