Errors
Every error from /api/v1 is JSON, whatever your Accept header, and uses one envelope:
{
"success": false,
"error_code": "validation_failed",
"error": "The customer id field is required. (and 4 more errors)",
"message": "The customer id field is required. (and 4 more errors)",
"errors": {
"customer_id": ["The customer id field is required."],
"issue_date": ["The issue date field is required."],
"due_date": ["The due date field is required."],
"currency": ["The currency field is required."],
"items": ["The items field is required."]
}
}
| Field | Meaning |
|---|---|
success |
Always false on an error. |
error_code |
The field to match on. A stable machine-readable code: validation_failed, business_rule_violation, unauthenticated, forbidden, not_found, server_error, or an endpoint's own code such as quote_locked, delivery_failed, payment_link_not_found. It never changes with the language. |
error |
Display text, the same sentence as message. Do not match on it: it is in the request's language, and a later API version may drop it. A few older endpoints still put their code here as well; it is also in error_code. |
message |
Human-readable reason, safe to display, in the request's language (see below). |
errors |
Field name → list of messages. Always an object — {} when the error is not about a specific field. |
Some responses add keys to the envelope (retry_after on 429, quota and actions on 402, error_codes per recipient on a failed credit-note send). Ignore keys you do not recognise.
Language
Messages follow the request's Accept-Language header: its first supported language, by the header's own weights (fr-BE,fr;q=0.9 → French). Supported: en, fr, nl, de, es, it, pt. Without a supported language, messages are in English. error_code is the same in every language.
Unexpected failures
A failure that is not a refusal written for you (a 5xx, or a refusal the server did not foresee) carries a generic message with a support reference, for example …quote reference 7KQ2M9XA. Quote it to support: the details are logged under that reference. The message never contains internal details.
Status codes
| Status | When |
|---|---|
400 |
Missing organization context, or a request the endpoint cannot act on |
401 |
Missing, invalid, revoked or expired token |
402 |
Plan quota reached — quota says which limit |
403 |
Insufficient permission or token scope; write on an archived organization |
404 |
Resource or route not found — or not accessible from your organization |
413 |
Upload exceeds your storage quota |
422 |
Validation failure, or a business rule refused the request (see below) |
429 |
Rate limit exceeded — honour Retry-After |
5xx |
Server error. The message never contains internal details; retry with backoff. |
OAuth endpoints (/oauth/*) are not part of /api/v1 and follow the OAuth 2.0 error format: { "error": "invalid_grant", "error_description": "..." }.
422: validation or business rule
Both use status 422 and the same envelope:
- Validation (
error_code: validation_failed): the request is malformed — a required field is missing, an id does not exist in your organization, a value is out of range — or it carries a key the endpoint does not take. The API is strict: every query parameter and body field outside an endpoint's documented contract is refused and named inerrors, so a typo can never be silently dropped. Three sentences tell you which kind:- unknown —
"`nmae` is not a parameter of this endpoint." - read-only —
"`total` is read-only; the server computes it."(response attributes echoed back on an update) - renamed —
"`start_date` is not a parameter of this endpoint; use `date_from`."Nested keys are reported by their real path (items.1.total).organization_idis a context parameter and is always accepted.
- unknown —
- Business rule (
error_code: business_rule_violation, or the endpoint's own code): the request is well-formed but refused — paying more than the balance due, billing an expense that is not billable, a document not eligible for VeriFactu. When one field is at fault it is named inerrors, e.g.errors.amount.
Do not retry a 422 unchanged; fix the request first.
Not found vs. not yours
A 404 on a resource you believe exists usually means it belongs to a different organization than the one your token or X-Organization-Id header selects. The API deliberately does not distinguish "does not exist" from "not yours". The same applies to ids in a request body: an id from another organization fails validation exactly like one that does not exist.