Error handling

The API distinguishes two things that are easy to confuse: request errors(your call could not be processed — reported as RFC 9457 problem+json with a 4xx status) and validation findings (the invoice has problems — reported inside the report, with HTTP 200). An invalid invoice is a successful validation.

Request errors: RFC 9457 problem+json

Whenever a request fails, the response has Content-Type: application/problem+jsonand this body structure:

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://billhorse.com/errors/unauthorized",
  "title": "unauthorized",
  "status": 401,
  "detail": "API key missing or invalid. Send header: Authorization: Bearer <key>"
}

HTTP status codes

422 on /parse

Unlike /validate — which always answers 200 with a report — /parseanswers 422 Unprocessable Content when no semantic invoice model could be extracted. The response body contains the validation report ({ "report": … }, withoutinvoice); its findings explain what was detected, e.g. BH-XML-01when the input is not well-formed XML:

HTTP/1.1 422 Unprocessable Content

{
  "report": {
    "valid": false,
    "findings": [
      { "id": "BH-XML-01", "severity": "error",
        "message": "The file is not well-formed XML." }
    ],
    …
  }
}

Message language (?lang=)

Finding messages come in English by default (the contract language of the API). Add ?lang=de or ?lang=fr to /validate and/parse to get German or French messages for your end users:

curl -s -X POST "https://api.billhorse.com/v1/validate?lang=de" \
  -H "Authorization: Bearer $BILLHORSE_API_KEY" \
  --data-binary @rechnung.xml

• Accepted values: de, en, fr. Region subtags work too (de-DE, fr-CH); anything else falls back to English.
• Only the finding message is localized. id, detail, expected, actual and found are language-neutral, so your error handling never depends on the language.
• problem+json request errors are not localized — their detail is always English.

Validation findings

Validation problems never surface as HTTP errors. They are entries in the report'sfindings array; valid is true iff no finding has severityerror, and counts aggregates findings per severity:

{
  "valid": false,
  "findings": [
    { "id": "BR-DE-15", "severity": "error",
      "message": "XRechnung: buyer reference (BT-10, …) is mandatory." },
    { "id": "BR-CO-16", "severity": "error",
      "message": "Amount due (BT-115) does not match …",
      "expected": "178.50", "actual": "170.00" }
  ],
  "counts": { "error": 2, "warning": 0, "info": 0 }
}

Optional fields are omitted entirely when not set (never null).

Rule id families

The full catalog with fixes lives in the rule index — in EN, DE and FR.