VALIDATION_ERROR

When it happens

Part of the request is not acceptable. With 422, the body parsed but a value breaks a rule: a missing required property, a length or range, a value outside an enum. error.details maps each offending property (snake_case, nested paths joined with a dot) to what is wrong with it. With 400, the problem is in the URL: an unknown query parameter, a value that does not parse, such as a malformed UUID or an unknown enum value, an empty element in a list filter (status=ISSUED,; a parameter sent entirely empty, status=, is the same as omitting it) or a sort_by the list does not sort by. error.details names the parameter.

How to fix it

Read error.details, correct each property it names, and send the request again.

HTTP status

This code can arrive with 422 Unprocessable Content or 400 Bad Request, depending on the operation. Branch on error.code, not on the status alone.

Retry

Not as is: the same request fails the same way. Fix the cause described above, then send the request again, under a new Idempotency-Key if the body changed.

Rules that cite this code

• VOI-002 Void an issued invoice through the void operation; delete a draft

Example response

When this error occurs, the API returns a JSON response with the following shape:

{
  "type": "https://docs.beel.es/errors/VALIDATION_ERROR",
  "title": "VALIDATION_ERROR",
  "detail": "The provided data is not valid.",
  "instance": "/v1/<resource>",
  "errors": [],
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid.",
    "details": {}
  },
  "meta": {
    "timestamp": "2026-05-21T10:00:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

The type URI is stable and always resolves to this page.

Message

Send the request with Accept-Language: <es|en|ca> to receive the message in your preferred language.

Other errors in this category

Keep exploring