Skip to content
On this page

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 in errors, 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_id is a context parameter and is always accepted.
  • 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 in errors, 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.