Response headers
Every response header Beliq sets, what it means, and which responses carry it.
Beliq reports a lot about each request in response headers, so you can log the audit trail without parsing the body (and read it at all when the body is raw PDF or XML bytes).
Two naming families, and the split is deliberate:
x-beliq-*carries platform facts that hold for any operation: which mode the key ran in, whether a quota unit was refunded.x-<thing>carries per-document detail from the validation engine: the syntax, the detected profile, the rule versions that ran.
A result header is present only when Beliq has that value to report. Absence means “not reported for this request”, not “empty” or “false”. Treat a missing header as unknown rather than defaulting it, and do not switch logic on an empty string.
On every response
| Header | Set on | Meaning |
|---|---|---|
x-request-id |
Every response, including errors | Request identifier (UUID) for log correlation. Quote it in a support request: it is the fastest way for us to find your call. |
x-beliq-livemode |
Every /v1/* response |
true on a live key, false on a test key. Lets an SDK surface sandbox vs. live without decoding the key. See Test mode. |
Validation result
Set by /v1/validate, /v1/parse and /v1/generate, each one only when the engine reported that value for your document.
| Header | Meaning |
|---|---|
x-syntax |
The document’s XML syntax: ubl or cii. This is the syntax, not the format or profile: an XRechnung and a Peppol BIS Billing 3.0 invoice are both ubl. |
x-profile-detected |
Profile inferred from the document’s CustomizationID / guideline URN, e.g. en16931, xrechnung, peppol-bis, facturx:basic. Absent when the document carries no profile URN. |
x-schematron-version |
Version of the EN 16931 Schematron that ran. Absent when no Schematron ran. |
x-validation |
One-line verdict summary, for logs and terminal output: pass · 0 err · 2 warn. The counts are the same errors and warnings arrays the JSON body carries; parse the body, not this string, when you need the detail. |
x-ruleset-sha256 |
Single fingerprint of the rule artifacts that judged the document. The header form of the body’s rulesetSha256. |
x-ruleset-artifacts |
JSON-encoded array of the component rows behind that fingerprint, { key, version, fileSha256 } each. |
x-ruleset-sha256 and x-ruleset-artifacts are the verifiability seal: you can reproduce the fingerprint yourself and cross-check every component against the public catalog. See Verify a hash and GET /v1/rulesets.
Ruleset pinning
| Header | Set on | Meaning |
|---|---|---|
Beliq-Ruleset-Resolved |
/v1/validate, when the request sent a Beliq-Ruleset header |
The ruleset that actually ran, so you can confirm your pin took effect: previous when a retained ruleset served the request, latest when nothing the request resolved had a retained ruleset the channel could reach, either because none is retained or because the authority has made its successor mandatory (which also sets rulesetFellBack in the body). See Ruleset versioning. |
Generate
| Header | Meaning |
|---|---|
x-pdf-kind |
hybrid (PDF/A-3 with the legal XML embedded) or visualization (human-readable rendering, no embedded XML). See PDF output for why the distinction matters. |
x-version-block |
Compact JSON object with the artifact versions in play for this request. Omitted when empty. |
The validation-result headers above are set on /v1/generate too, since generating validates.
Convert
POST /v1/convert documents its own audit headers: x-source-format, x-target-format, x-profile-detected, x-lost-elements, x-lost-elements-count, x-conversion-tools, x-output-envelope and x-version-block. The conversion’s lossiness audit trail lives in those headers because the response body is raw bytes.
Throttling
x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset and Retry-After are documented with the limits themselves, in Authentication and limits.
Quota refunds
| Header | Set on | Meaning |
|---|---|---|
x-beliq-quota-refunded |
Error responses where a Beliq-side engine outage was to blame | true if the document’s quota unit was returned to your balance, false if the refund was attempted and could not be applied. Absent when no refund was applicable, which is the normal case for an error you caused. |
Reading headers from a browser
A cross-origin browser client can only read response headers a server explicitly exposes. Beliq exposes:
x-request-id, x-syntax, x-profile-detected, x-schematron-version, x-validation, x-ruleset-sha256, x-ruleset-artifacts, x-version-block, x-pdf-kind, x-source-format, x-target-format, x-lost-elements, x-lost-elements-count, x-conversion-tools, x-output-envelope, Beliq-Ruleset-Resolved, Retry-After, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset.
x-beliq-livemode and x-beliq-quota-refunded are not exposed, so read them from a server-side call rather than browser JavaScript.
Example
curl -i -X POST https://api.beliq.eu/v1/validate \
-H "Authorization: Bearer $BELIQ_API_KEY" \
-H "Content-Type: application/xml" \
--data-binary @invoice.xmlHTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-request-id: 3f2a9c14-7b5e-4d8a-9e01-6c4b2f8a1d33
x-beliq-livemode: true
x-syntax: ubl
x-profile-detected: xrechnung
x-schematron-version: XRechnung-2.6.0
x-validation: pass · 0 err · 2 warn
x-ruleset-sha256: 7a590a263701e50305677ec253c61d83a13336c0e8b10b01674573347a52de00
x-ratelimit-limit: 300
x-ratelimit-remaining: 299
x-ratelimit-reset: 41