> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.invoice-api.xhub.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.invoice-api.xhub.io/_mcp/server.

## Upcoming enforcement

These limits warn today and will be rejected with **400** in a later release. We will announce that release in
advance — watch for the warnings now.

| Warning                          | Field                                                                    | Limit                                                                       |
| -------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| `FIELD_TOO_LONG`                 | `seller.` / `buyer.` `street`, `additionalStreet`                        | 200 characters                                                              |
| `FIELD_TOO_LONG`                 | `seller.` / `buyer.` `city`                                              | 100 characters                                                              |
| `FIELD_TOO_LONG`                 | `seller.` / `buyer.` `postalCode`                                        | 20 characters                                                               |
| `FIELD_TOO_LONG`                 | `seller.state`, `buyer.state`, `delivery.address.state`, `projectNumber` | 100 characters                                                              |
| `FIELD_TOO_LONG`                 | `attachments`                                                            | 20 attachments; 15 MiB decoded each; 30 MiB decoded together                |
| `INVOICE_LINES_ABOVE_MODE_LIMIT` | `items`                                                                  | 5000 lines including sub-items, on servers without large-invoice validation |

The warnings appear on `/generate`, `/embed` and `/validate`. Leading and trailing spaces do not count, except for
`projectNumber`.

## Sub-items count as lines; depth and body limits

* All lines together — top-level items and sub-items at any depth — may not exceed **25,000**. Above that: **400**
  with `params.code: "TOO_MANY_INVOICE_LINES"`, `count` and `limit`.
* Sub-items may be nested at most **100** levels. Deeper: **400** `SUB_ITEMS_TOO_DEEP` with `depth` and `path`.
* The request body is limited to **128 MiB** on every route. This was already the limit; it now answers **413**
  with `error: "PAYLOAD_TOO_LARGE"` and `limit` in bytes. Attachments travel in the same body.

The plan limit `TOO_MANY_LINE_ITEMS` still counts top-level items only.

## Czech ISDOC in a foreign currency needs the exchange rate

If `currency` is not `CZK`, `/CZ/isdoc/generate` needs `countrySpecific.exchangeRate` (CZK for 1 unit of your
currency). Without it the request fails with `CZ_ISDOC_EXCHANGE_RATE_REQUIRED` on that field. With it, the document
carries all amounts in both currencies, as ISDOC requires. There was no warning phase: the old output ("1 EUR = 1 CZK",
no CZK amounts) never passed the ISDOC check. CZK invoices do not change.

## Unreadable dates answer 400 `INVALID_DATE`

On `/generate`, `/embed` and `/convert`, in all formats, a date that cannot be read (for example `not-a-date`, or
`2026-13-01` in a `/convert` source) now answers **400** with `code: "INVALID_DATE"` and the `field`. Before, it failed
at the XML schema with 422 and no field. Facturae, myDATA and NAV still answer 422 `XSD-ERROR` for now.

**Do I need to act?** If you handle 422 for bad dates, also handle 400 `INVALID_DATE`. See the 2026-10-18 entry for
readable dates that are not `YYYY-MM-DD`.

## Invalid unit codes are replaced, not rejected

An `items[].unit` that is not a UN/ECE Recommendation 20 code is written as `C62` ("one"), together with the price base
unit, and the response warns with `UNIT_CODE_SUBSTITUTED` at `items.N.unit`. Before, some formats rejected the invoice
(for example Peppol rule R130). Send a Rec 20 code such as `H87` or `HUR` to avoid the warning.

## `null` means omitted

On `/generate`, `/embed` and both `/validate` routes, an optional field sent as `null` is the same as leaving it out.
An object whose fields are all `null` counts as omitted. A required field sent as `null` is rejected like a missing one
(400 with the path) — for example `servicePeriod` with `start` set and `end: null`.

**`payloadHash` changes once** for invoices that contain `null` fields: it is now the hash without them. If you use
`payloadHash` or `X-Payload-Hash` as a key, expect a new value for those invoices.

In the OpenAPI file, optional input fields are nullable and request line items use the type `InvoiceLineItemInput`.
Response types do not change.

## 400 validation errors are documented

A request body that fails the input check answers `{ "success": false, "error": [ … ] }`, each entry with `code`,
`path` and `message` (plus `maximum`, `minimum`, `expected`, `values` or `keys` where relevant). This was always the
behaviour; the 400 of every JSON route now lists it as `RequestValidationError`. Regenerate your client to read the
field paths. `POST /api/v1/invoice/convert` is not affected.

## Busy server: 503 with `Retry-After`; server errors carry an `errorId`

* Generating, embedding, converting and validating run with a limited number of parallel calls, per server and per
  organization. If no slot is free within about 2 seconds you get **503** `SERVER_BUSY` with a `Retry-After` header.
  Nothing is billed. Wait and retry.
* A **500** now has `code: "INTERNAL_ERROR"` and an `errorId` (UUID) — send it to support. The answer never contains
  internal details. This also covers `GET /api/v1/verifactu/chain/{vatId}/export`, `POST /api/v1/lroe/submit` (no more
  `detail` field) and `POST /api/v1/pdf/attachments`.
* A brief database problem gives **503** `SERVICE_UNAVAILABLE` with `errorId` and `Retry-After` instead of 500.
* A call that ends with a 5xx is not billed.

All changes are additive; `error` and `message` remain.

## New endpoint: upload your carrier PDF as a file

`POST /api/v1/invoice/{country}/{format}/embed/upload` takes the `/embed` request as `multipart/form-data`: `pdf` (file
part), `invoice` (JSON text), optional `validate` and `formatOptions`. Same checks, entitlement and price as `/embed`.

* **Binary answer:** with `Accept: application/pdf` you get the hybrid PDF itself — only when there is nothing to
  report (check passed or skipped, no `warnings`, no `carrier.warnings`). Otherwise you get the JSON answer. Headers:
  `X-Validation-Status`, `X-Hash`, `X-Payload-Hash`, `X-Result-Rechecked`.
* **Large carriers:** up to **64 MiB** on this route. Above 15 MiB the result is not re-opened for checking
  (`PDF_RESULT_NOT_RECHECKED`, `X-Result-Rechecked: false`). If the embedding service is unavailable for such a
  carrier: **503** `EMBED_UNAVAILABLE` with `Retry-After: 60`, not billed.
* **Signed carriers (both embed routes):** we keep the signature valid. If that is not possible, you get
  `CARRIER_SIGNATURE_INVALIDATED` (or `CARRIER_CERTIFICATION_INVALIDATED`) instead of a silently broken signature.
* **New warning on both embed routes:** `CARRIER_FONTS_NOT_CHECKED` when the carrier could not be opened for the font
  check. Nothing is rejected.

`/embed` itself does not change and never answers binary.

## Rulebook check with a time limit

The rulebook check now stops after a time limit, mainly for ZUGFeRD / Factur-X EXTENDED with many sub-items. You still
get your document (200) with the warning `SELF_CHECK_INCOMPLETE`. With `validate: true`, `validation.status` is
`not_run`, `valid` is `null` and `validation.reason` is `time-budget`. A second new reason, `sidecar-unavailable`,
replaces `transform-failed` when our check service did not answer for a document too large to check without it.

## Smaller changes

* **ISDOC:** a VAT category ISDOC cannot carry (anything except `S`, `O` and domestic `AE`) now adds the warning
  `ISDOC_TAX_CATEGORY_NOT_REPRESENTABLE` (`params.category`, `params.positions`, `lossy: true`). Nothing is rejected.
* **XRechnung UBL, category `E` without a reason:** the substituted reason is now the text `Exempt from VAT` without a
  code, instead of `VATEX-EU-132`. With `countrySpecific.isKleinunternehmer: true` it is the small-business notice valid
  on `issueDate`. Warning `DE_TAX_EXEMPTION_REASON_SUBSTITUTED` as before. A reason you send is never changed; CII is
  unchanged.
* **PDF:** the default templates no longer need `seller.bankAccount.iban` (the IBAN line is left out) or `buyer.name`.
  On the Swiss and Liechtenstein payment part without a payer, the "Payable by (name/address)" box is shown empty, as
  SIX IG v2.4 requires. Invoices with buyer, IBAN and buyer country look exactly as before.