Errors

One envelope for every error, with a machine-readable code, grouped by resource.

Every error uses the same envelope, in English:

{
  "error": {
    "code": "invalid_filter",
    "message": "Invalid type 'x'. Allowed: [...]"
  }
}

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

validation_error · 422

Body or parameter failing schema validation; message is field: reason.

invalid_filter · 400

Unknown value in a list filter (also unknown language on reference lists, unknown format on file download).

invalid_parameter · 422

Query parameter that does not apply to the targeted resource (e.g. ?ignore_duplicate on a contact).

field_not_editable · 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.

not_found · 404

Unknown route or unknown UUID (including a UUID of another company).

internal_error · 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

invalid_request · 400

Missing credential field on /auth/token.

invalid_credentials · 401

Unknown client_id or wrong client_secret.

invalid_grant · 401

Unknown, already-used or revoked refresh_token.

client_inactive · 401

The client has been deactivated.

invalid_token · 401

Missing, malformed or expired access_token.

insufficient_permissions · 403

The access_token lacks the required permission.

too_many_requests · 429

Too many failed authentications on this client_id.

Documents

invalid_relation · 422

relation_id unknown, belonging to another company, or with no address.

invalid_journal · 422

Journal unknown, inactive, of another company, or of the wrong category for the document type.

no_default_journal · 422

No journal_id given and the company has no default journal for the category.

invalid_delivery_location · 422

Delivery location unknown or belonging to another relation than the document’s.

invalid_amount · 422

Document total negative.

invalid_paid_amount · 422

Declared paid_amount above the document total.

invalid_allowance_charge · 422

Document-level discount/charge on lines totalling 0, or a VAT rate whose lines total a negative amount.

invalid_issue_date · 422

Date outside the bracket of the neighbouring numbered documents, or outside the numbering window.

invalid_document_lines · 422

Stored lines that cannot be reused for a recompute — send the full lines array instead.

self_billing_disabled · 422

Creating a purchase document while self-billing is not enabled for the company.

not_sendable · 422

Sending a document type Peppol does not transport (e.g. a proforma). As a 409: sending a received document.

send_failed · 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.

already_sent · 409

Peppol send on a document already sent — only a failed send (peppol_status failed or rejected) can be retried.

duplicate_attachment · 409

Attachment filename already present on the document.

document_not_editable · 409

PATCH on a document already sent to the customer, already transmitted to accounting, or received.

document_not_deletable · 409

DELETE on a document that is not the last of its sequence, already sent, transmitted, or received.

document_in_use · 409

DELETE on a document linked to a reconciliation, an invoiced timesheet line or a payment intent.

Import and attachments also return plain HTTP statuses: 413 (file too big) and 415 (extension not allowed).

Relations

duplicate_relation · 409

Company whose vat, identifier or electronic_address already exists — bypass with ?ignore_duplicate=true; the message gives the existing id.

invalid_address · 422

Address without country_code, or street_number without street.

relation_in_use · 409

DELETE on a relation still referenced (document, subscription, project, timesheet line, accounting match…). The message says what blocks.

Delivery locations

invalid_address · 422

Address without country_code, or street_number without street — the same rules as a relation’s address.

invalid_identifier · 422

identifier / identifier_scheme pair half-filled.

invalid_delivery_location · 422

On a document: location unknown or belonging to another relation than the document’s.

delivery_location_in_use · 409

DELETE on a delivery location a document is delivered to.

Bank accounts

duplicate_bank_account · 409

Account with the same reference (IBAN) already exists.

default_account_required · 422

Demoting the default bank account without promoting another.

Journals

duplicate_journal_code · 409

Journal code already used in the company.

default_journal_required · 422

Default journal created or left inactive, or demoting the last default of a category.

invalid_bank_account · 422

bank_account_id matching no account of the company.

Brandings

default_branding_required · 422

Demoting the default branding — promote another instead.