Errors
75 error codes and 37 error classes across 4 package(s), extracted directly from source at revision 5ab878035219.
Every error the packages raise carries a code — stable across releases, the thing to branch on or search for — and a docsUrl pointing at its entry below. The message may change between releases; the code does not. A document the Medusa plugin did not issue shows its code in the order's "E-Invoices" block, linked here.
Codes — @normwerk/einvoice-cii
UNMAPPED_INVOICE_FIELDS
The invoice carries a field the CII serialization does not write yet (listed in the message). It is refused rather than dropped from the XML without a trace. Leave the field out, or map it only once a release writes it — see the mapping reference for the fields it writes.
Source: packages/einvoice-cii/src/error-codes.ts:9
UNREPRESENTABLE_CHARACTER
A value — a product name, an address — contains a control character that XML 1.0 cannot carry, not even escaped; the document would not parse. Remove the character from the source data.
Source: packages/einvoice-cii/src/error-codes.ts:12
Codes — @normwerk/einvoice-commerce
BUYER_VAT_ID_DOMESTIC
An intra-EU supply needs a VAT-ID issued by another member state; the buyer's is German.
Source: packages/einvoice-commerce/src/error-codes.ts:20
BUYER_VAT_ID_MISMATCH
The VAT-ID the evidence or the document names is not the buyer's VAT-ID the decision was made on.
Source: packages/einvoice-commerce/src/error-codes.ts:22
CHARGE_SPLIT_IMPOSSIBLE
Shipping or a document-level discount cannot be split across the invoice's VAT rates: the lines add up to zero at every rate.
Source: packages/einvoice-commerce/src/error-codes.ts:74
CHARGED_RATE_MISMATCH
A domestic line is classified at one German rate but was charged the other.
Source: packages/einvoice-commerce/src/error-codes.ts:59
CREDIT_EXCEEDS_INVOICE
A credit exceeds what is still uncredited on the invoice it corrects.
Source: packages/einvoice-commerce/src/error-codes.ts:129
CROSS_BORDER_SERVICE_UNDECLARED
A service to a business in another EU member state. Its category (AE, reverse charge) is only applied when declared: set the regime override reverse-charge-cross-border on the order.
Source: packages/einvoice-commerce/src/error-codes.ts:18
DECISION_CARRIED_TO_INVOICE
A tax decision was carried over to a document that is not a credit note. An invoice is decided on the facts of its own supply; only a credit note follows the decision of the invoice it corrects.
Source: packages/einvoice-commerce/src/error-codes.ts:134
DELIVERY_NOT_INTRA_EU
An intra-EU supply needs the goods delivered to another EU member state; the deliver-to country is Germany, outside the EU, or missing.
Source: packages/einvoice-commerce/src/error-codes.ts:29
DUPLICATE_BUYER_REFERENCE
Both a buyer reference and a Leitweg-ID were given; the invoice holds one. For a public-sector buyer, give the Leitweg-ID alone.
Source: packages/einvoice-commerce/src/error-codes.ts:115
EXPORT_DELIVERED_IN_EU
An export needs the goods to leave the EU; they are delivered inside it.
Source: packages/einvoice-commerce/src/error-codes.ts:31
INVALID_ASSEMBLED_INVOICE
The invoice buildInvoice assembled fails the model's own validation — a defect in this package; please report it.
Source: packages/einvoice-commerce/src/error-codes.ts:127
INVALID_CHARGED_RATE
The rate a line was charged is not a VAT rate (a percentage such as 19).
Source: packages/einvoice-commerce/src/error-codes.ts:54
INVALID_INPUT
The input fails structural validation against the CommerceInvoiceInput JSON Schema; the message lists where.
Source: packages/einvoice-commerce/src/error-codes.ts:95
INVALID_LEITWEG_ID
The declared Leitweg-ID is not valid: its format or check digits are wrong.
Source: packages/einvoice-commerce/src/error-codes.ts:112
INVALID_PAID_AMOUNT
The amount stated as already paid is negative or more than the invoice total.
Source: packages/einvoice-commerce/src/error-codes.ts:131
INVALID_PRICE_BASIS
A price or charge must be given either net or including VAT — exactly one of the two.
Source: packages/einvoice-commerce/src/error-codes.ts:124
INVOICED_RATE_ON_INVOICE
A line of an invoice carries the rate of an invoice it corrects. Only a credit note's lines are credited at the rate their invoice stated.
Source: packages/einvoice-commerce/src/error-codes.ts:137
LINE_ALLOWANCE_EXCEEDS_LINE
A line's discounts exceed its own amount.
Source: packages/einvoice-commerce/src/error-codes.ts:110
LINE_RATE_UNKNOWN
A domestic line has neither a rate classification nor a charged rate, so its rate cannot be resolved.
Source: packages/einvoice-commerce/src/error-codes.ts:66
MISSING_BUYER_IDENTIFIER_REVERSE_CHARGE
A reverse-charge supply needs the buyer's VAT-ID or legal registration identifier on the document.
Source: packages/einvoice-commerce/src/error-codes.ts:105
MISSING_BUYER_VAT_ID
An intra-EU supply needs the buyer's VAT-ID on the document itself.
Source: packages/einvoice-commerce/src/error-codes.ts:103
MISSING_BUYER_VAT_ID_CROSS_BORDER_SERVICE
A service to a business in another EU member state under reverse charge needs the buyer's VAT-ID on the invoice (§14a Abs. 1 UStG); a registration identifier alone is not enough.
Source: packages/einvoice-commerce/src/error-codes.ts:108
MISSING_CORRECTED_INVOICE_REFERENCE
A credit note must name the invoice it corrects.
Source: packages/einvoice-commerce/src/error-codes.ts:97
MISSING_DOCUMENT_NUMBER
The document has no number; buildInvoice does not allocate one itself.
Source: packages/einvoice-commerce/src/error-codes.ts:99
MISSING_ELECTRONIC_ADDRESS
The seller's or the buyer's electronic address, with its scheme, is required (an email address with scheme EM will do). For a buyer, it is the order's email address.
Source: packages/einvoice-commerce/src/error-codes.ts:122
MISSING_INTRA_EU_DELIVERY
An intra-EU supply needs the delivery date and the deliver-to country on the document.
Source: packages/einvoice-commerce/src/error-codes.ts:101
MISSING_SELLER_ADDRESS
The seller's street is required on every invoice (§14 Abs. 4 Satz 1 Nr. 1 UStG).
Source: packages/einvoice-commerce/src/error-codes.ts:119
MISSING_SELLER_CONTACT
The seller's contact — name, telephone, email — is required on every invoice (BR-DE-2).
Source: packages/einvoice-commerce/src/error-codes.ts:117
MIXED_SUPPLY_CROSS_BORDER
A cross-border order with goods and services on one document has no single category. Issue two invoices, one per kind of supply, or classify the service as part of the goods if it is ancillary to them.
Source: packages/einvoice-commerce/src/error-codes.ts:85
NO_TAX_RULE
No rule matches the order's facts — seller, buyer country, business or consumer, OSS registration. Refused rather than guessed.
Source: packages/einvoice-commerce/src/error-codes.ts:77
NO_VAT_CHARGED
No line and no shipping of a domestic order carries VAT: the shop charged none. Either its tax settings have no German VAT rate for the sale, or the seller is a Kleinunternehmer (§19 UStG). A Kleinunternehmer may always send an ordinary invoice instead of an e-invoice (§34a Satz 4 UStDV); this release does not issue invoices for them.
Source: packages/einvoice-commerce/src/error-codes.ts:71
NON_EU_SERVICE_UNSUPPORTED
A service to a business outside the EU. Whether it is AE, O or G is not settled, and this release refuses rather than guesses. Issue this invoice outside the plugin.
Source: packages/einvoice-commerce/src/error-codes.ts:40
OSS_RATE_INVALID
The declared OSS rate is not a VAT rate above zero.
Source: packages/einvoice-commerce/src/error-codes.ts:44
OSS_RATE_MISMATCH
An OSS line was charged another rate than the declared destination rate.
Source: packages/einvoice-commerce/src/error-codes.ts:52
OSS_RATE_MISSING
An OSS distance sale needs the destination country's VAT rate declared on the order.
Source: packages/einvoice-commerce/src/error-codes.ts:42
OSS_REDUCED_RATE_UNSUPPORTED
An OSS order with a reduced-rate line. The declared OSS rate is one rate for the order, the destination's standard rate; a reduced destination rate cannot be declared yet.
Source: packages/einvoice-commerce/src/error-codes.ts:50
OSS_SERVICES_UNSUPPORTED
A service to a consumer in another EU member state under OSS. This release covers OSS sales of goods only: whether a service is taxed in Germany or in the consumer's country cannot be read from the order.
Source: packages/einvoice-commerce/src/error-codes.ts:47
OVERRIDE_OUT_OF_SCOPE
A declared regime override does not fit the order: exempt or zero-rated for a buyer outside Germany, domestic reverse charge for anything but a German business buyer, cross-border reverse charge for anything but a service to a business in another EU member state. Remove the override or correct it.
Source: packages/einvoice-commerce/src/error-codes.ts:15
RATE_NOT_IN_FORCE_ON_SUPPLY_DATE
A domestic line was charged a German VAT rate of another period than the day it was supplied — the rate changed between the order and its delivery. Issue this invoice outside the plugin.
Source: packages/einvoice-commerce/src/error-codes.ts:62
SPECIAL_VAT_TERRITORY
The goods go to, or the service's buyer is in, a territory whose VAT treatment differs from its country code's: Heligoland or Büsingen (DE), the Canary Islands, Ceuta or Melilla (ES), the Åland Islands (FI), a French overseas department or territory, Mount Athos (GR), Livigno or Campione d'Italia (IT) — outside the EU VAT area — or Northern Ireland, inside it for goods. Recognised by postcode. This release does not model them; issue this invoice outside the plugin.
Source: packages/einvoice-commerce/src/error-codes.ts:37
SUPPLY_DATE_BEFORE_RATE_TABLE
The supply date is before the first day this package knows Germany's VAT rates for (2007-01-01).
Source: packages/einvoice-commerce/src/error-codes.ts:64
UNSUPPORTED_BUYER_COUNTRY
The buyer's country is not supported yet by this release.
Source: packages/einvoice-commerce/src/error-codes.ts:87
UNSUPPORTED_BUYER_COUNTRY_CLEARANCE
The buyer's country — Italy or Poland — runs a mandatory clearance platform with its own national XML; no EN 16931 document can be submitted through it. Out of scope.
Source: packages/einvoice-commerce/src/error-codes.ts:90
UNSUPPORTED_CHARGED_RATE
A domestic line was charged a rate that is neither of Germany's (19 %, 7 %). Check the shop's tax settings for the product, region and shipping option.
Source: packages/einvoice-commerce/src/error-codes.ts:57
UNSUPPORTED_SCHEMA_VERSION
CommerceInvoiceInput.schemaVersion names a version this release does not know.
Source: packages/einvoice-commerce/src/error-codes.ts:92
UNSUPPORTED_SELLER_COUNTRY
The seller is not established in Germany. The VAT rules, rates and invoice requirements this release applies are German law.
Source: packages/einvoice-commerce/src/error-codes.ts:11
VAT_ID_UNVERIFIED
An intra-EU supply (category K) needs the buyer's VAT-ID confirmed valid — a positive VIES check — or a declared manual confirmation (regime override intra-eu-confirmed). Most often VIES was unavailable or did not confirm the number: issue the invoice once it does, or declare how you confirmed it.
Source: packages/einvoice-commerce/src/error-codes.ts:26
Codes — @normwerk/einvoice-conformance
CREDIT_NOTES_NOT_ASSESSED
This release's dry run plans invoices only: a refund or a cancellation is listed, not planned.
Source: packages/einvoice-conformance/src/dry-run/report.ts:209
ORDER_CHANGED_AFTER_SHIPMENT
The order changed after this fulfillment — changes says how. The run reads the order as it is now, not as it was when the invoice would have been issued, so it does not judge the invoice.
Source: packages/einvoice-conformance/src/dry-run/report.ts:212
SHOP_PDF_NOT_ASSESSED
The shop renders its own PDF for the invoices. The run does not call it, so whether that PDF can become PDF/A-3 is not assessed; the XML is.
Source: packages/einvoice-conformance/src/dry-run/report.ts:222
Codes — @normwerk/einvoice-medusa
CHARGED_TOTALS_MISSING
Not issued: Medusa returned no order total or VAT total to check the invoice against.
Source: packages/einvoice-medusa/src/mapping/charged-reconciliation.ts:79
FULFILLMENT_MISSING
A fulfillment the plugin was asked to invoice is not on the order any more.
Source: packages/einvoice-medusa/src/errors.ts:60
INTERNAL_ERROR
An unexpected error — a defect, or a failure of Medusa or a service it calls. The message says what happened; retry, and report it if it persists.
Source: packages/einvoice-medusa/src/errors.ts:63
INVALID_PLUGIN_OPTIONS
The plugin options in medusa-config.ts are incomplete or invalid; the message names the option. The plugin does not start.
Source: packages/einvoice-medusa/src/errors.ts:21
INVOICE_TOTAL_MISMATCH
Not issued: the invoice total does not match what Medusa charged, and a difference in VAT does not explain it — or the order mixes prices with and without VAT. Correct the order and retry, or issue this invoice outside the plugin.
Source: packages/einvoice-medusa/src/mapping/charged-reconciliation.ts:77
INVOICE_VAT_ABOVE_CHARGED
Not issued: the invoice would state more VAT than Medusa charged, and so a higher total than the buyer paid — VAT stated on an invoice is owed (§14c UStG). Correct the tax rate in Medusa and the order's tax lines, then retry.
Source: packages/einvoice-medusa/src/mapping/charged-reconciliation.ts:73
MISSING_BUYER_COUNTRY
The order has no country on its billing or shipping address, so neither the VAT nor the document profile can be decided.
Source: packages/einvoice-medusa/src/errors.ts:30
MISSING_ORIGINAL_INVOICE
A refund or cancellation for an order whose invoice the plugin did not issue — not yet, or before the plugin was installed. Issue the invoice first, then retry the credit note.
Source: packages/einvoice-medusa/src/errors.ts:33
PDF_ENCRYPTED
Issued as XML alone: the PDF from standalone.basePdf is encrypted, which PDF/A does not allow.
Source: packages/einvoice-medusa/src/pdf.ts:20
PDF_FONT_NOT_EMBEDDED
Issued as XML alone: the PDF from standalone.basePdf uses a font it does not embed — typically a standard font such as Helvetica — and PDF/A requires every font embedded. Embed the fonts where the PDF is rendered, or use renderInvoicePdf.
Source: packages/einvoice-medusa/src/pdf.ts:18
PRICE_CHANGED_AFTER_INVOICE
Issued, then a price on it was changed in Medusa by an order edit. Lowered: refunding the difference issues a credit note on this invoice. Raised: the difference is not invoiced — issue an additional invoice outside the plugin.
Source: packages/einvoice-medusa/src/mapping/price-change.ts:20
REFUND_NEEDS_MANUAL_CREDIT
A refund the plugin cannot tie to one invoice: the order was invoiced per shipment, or part of it is paid but not shipped yet, and the refund names no goods that came back. A refund for goods never shipped needs no credit note; for anything else, issue the credit note outside the plugin.
Source: packages/einvoice-medusa/src/errors.ts:58
REFUND_ON_CLAIM_REPLACEMENT
A refund on an order with a claim with a replacement — the postage of a warranty case, for one — does not reduce a price: no credit note. Credit any part that does outside the plugin.
Source: packages/einvoice-medusa/src/errors.ts:51
REFUND_ON_EXCHANGE
A refund on an order with an exchange settles the exchange rather than reducing a price: no credit note. Credit any part that does reduce a price outside the plugin.
Source: packages/einvoice-medusa/src/errors.ts:48
SHIPMENT_ITEM_WITHOUT_LINE
A fulfillment ships an item that names no order line, so the invoice cannot state it. Issue this invoice outside the plugin.
Source: packages/einvoice-medusa/src/errors.ts:39
SHIPMENT_LINE_UNKNOWN
A fulfillment ships an order line the order no longer states a price for — every unit of it came back before the invoice was issued. Issue this invoice outside the plugin.
Source: packages/einvoice-medusa/src/errors.ts:36
SHIPMENT_OF_CLAIM_REPLACEMENT
A fulfillment ships a replacement from a claim. A warranty replacement needs no invoice, and VAT stated on one would be owed (§14c Abs. 1 UStG). If the replacement is sold, invoice it outside the plugin.
Source: packages/einvoice-medusa/src/errors.ts:45
SHIPMENT_OF_EXCHANGE
A fulfillment ships the new item of an exchange. The returned item has to be reversed with it, which the plugin does not do: invoice the new item, and credit the returned one, outside the plugin.
Source: packages/einvoice-medusa/src/errors.ts:42
SHIPMENT_QUANTITY_UNKNOWN
The order does not record how many units of a line a fulfillment shipped. Medusa records it with every fulfillment it creates for an order; issue this invoice outside the plugin.
Source: packages/einvoice-medusa/src/errors.ts:54
UNSUPPORTED_MEDUSA_VERSION
The installed Medusa release is outside the releases the plugin supports; see the compatibility table of the plugin's README. The plugin does not start.
Source: packages/einvoice-medusa/src/errors.ts:27
UNSUPPORTED_PLUGIN_OPTION
An option the plugin does not have, such as integration: the plugin issues its own invoices and does not embed its XML into another plugin's PDF. Remove the option.
Source: packages/einvoice-medusa/src/errors.ts:24
VAT_DIFFERS_FROM_MEDUSA
Issued. Prices including VAT: the buyer paid the invoice total, but Medusa counts a different VAT than the invoice. Nothing to refund; take VAT from the invoices, not from Medusa's order totals, and check Medusa's tax rates for the order's region, products and shipping option.
Source: packages/einvoice-medusa/src/mapping/charged-reconciliation.ts:66
VAT_OVERCHARGED
Issued. Prices without VAT: the invoice states less VAT than Medusa charged — typically a business buyer in another EU member state, invoiced at 0 % — and the buyer paid the difference on top. Refund the amount the notice names; that refund issues no credit note.
Source: packages/einvoice-medusa/src/mapping/charged-reconciliation.ts:62
Error classes — @normwerk/einvoice-cii
UnmappedInvoiceFieldsError
An Invoice field the serialization plan has no place for. The model carries some business terms this package does not write yet (BT-6/7/8, BT-111, BG-24, BG-26, BG-32); without this refusal they were dropped from the XML without a trace.
Source: packages/einvoice-cii/src/index.ts:43
UnrepresentableCharacterError
No doc comment on this class in the source.
Source: packages/einvoice-cii/src/serialize.ts:25
Error classes — @normwerk/einvoice-commerce
CreditExceedsInvoiceError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/credit-allocation.ts:54
DecisionCarriedToInvoiceError
correctedInvoiceDecision given for an invoice.
Source: packages/einvoice-commerce/src/build-invoice.ts:249
DuplicateBuyerReferenceError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:175
InvalidAssembledInvoiceError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:238
InvalidCommerceInvoiceInputError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:286
InvalidLeitwegIdError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:160
InvalidPaidAmountError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:272
InvalidPriceBasisError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:214
InvoicedRateOnInvoiceError
A line of an invoice carries invoicedVatRate.
Source: packages/einvoice-commerce/src/build-invoice.ts:261
LineAllowanceExceedsLineAmountError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:145
MissingBuyerIdentifierForReverseChargeError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:120
MissingBuyerVatIdError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:107
MissingBuyerVatIdForCrossBorderServiceError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:132
MissingCorrectedInvoiceReferenceError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:72
MissingDeliveryInfoForIntraCommunitySupplyError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:95
MissingDocumentNumberError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:84
MissingElectronicAddressError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:198
MissingSellerAddressError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:225
MissingSellerContactError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:186
MixedSupplyCrossBorderError
A cross-border order with supplyType: "mixed" has no single correct category for the whole document — its own distinct class (not generic TaxRuleError) so a caller can catch this specific, expected-and-actionable refusal instead of pattern-matching message text, which would break the moment the message wording changes.
Source: packages/einvoice-commerce/src/tax-rules.ts:62
TaxRuleError
A refusal to decide the VAT, with the docs/tax-semantics.md row it is about (ruleId) and why (code).
Source: packages/einvoice-commerce/src/tax-rules.ts:47
UnsupportedCountryError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/profile.ts:42
UnsupportedSchemaVersionError
No doc comment on this class in the source.
Source: packages/einvoice-commerce/src/build-invoice.ts:62
Error classes — @normwerk/einvoice-medusa
InvalidEinvoiceModuleOptionsError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/modules/einvoice/service.ts:133
MissingBuyerCountryError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/mapping/order-to-commerce-invoice-input.ts:239
MissingOriginalInvoiceError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/subscribers/credit-note-on-payment-refunded.ts:139
PluginError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/errors.ts:98
RefundNeedsManualCreditError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/subscribers/credit-note-on-payment-refunded.ts:152
RefundOnReplacementError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/mapping/replacement.ts:100
ReplacementShipmentError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/mapping/replacement.ts:66
ShipmentItemWithoutLineError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/mapping/shipment.ts:98
ShipmentLineUnknownError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/mapping/shipment.ts:69
ShipmentQuantityUnknownError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/mapping/shipment.ts:84
UnsupportedMedusaVersionError
No doc comment on this class in the source.
Source: packages/einvoice-medusa/src/medusa-version.ts:107
Error classes — @normwerk/einvoice-model
EinvoiceError
No doc comment on this class in the source.