Invoice API — Error Reference

All errors returned by the Invoice API follow a consistent envelope:

{
    "status": 400,
    "title": "Bad Request",
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "errors": [
        {
            "code": "Payment.InsufficientValue",
            "description": "Delivered value (0.00) is less than the amount to pay (100.00).",
            "type": 1,
            "furtherInformations": {
                "deliveredValue": 0.0,
                "totalToPay": 100.0
            }
        }
    ]
}

Errors are grouped by category below. Unless noted, all validation errors map to HTTP 400 Bad Request; infrastructure errors map to HTTP 500 Internal Server Error.

Document Type

Code	HTTP	Condition	Resolution
`DocumentType.NotSupported`	400	The document type's invoice nature is not whitelisted by the engine (e.g. receipt RE, or an unknown nature).	Use a supported document type — see Supported Document Types.
`DocumentType.InactiveOrMissing`	400	The `documentTypeId` refers to an inactive or non-existent document type.	Confirm the document type is active in the back-office.
`DocumentType.NotFound`	404	No document type found with the supplied `documentTypeId`.	Supply a valid `documentTypeId`.
`DocumentSeries.NotFound`	404	No document series found with the supplied `serieId`.	Supply a valid `serieId`.
`DocumentSeries.InactiveOrMissing`	400	The `serieId` refers to an inactive or non-existent series.	Confirm the series is active in the back-office.

Payment

Code	HTTP	Condition	Resolution
`Payment.InsufficientValue`	400	The total delivered amount is less than the document total.	Increase the delivered amount or add additional payment entries to cover the full total.
`Payment.DeliveredMustMatchTotal`	400	The document type requires an exact match between delivered amount and document total (no change or underpayment allowed).	Ensure the single payment entry's amount equals the document total exactly.
`Payment.MultipleEntriesNotAllowed`	400	More than one payment entry was supplied for a document type with optional payments (no cashier or checking-account flow active).	Supply at most one payment entry.
`Payment.MechanismNotAllowed`	400	A payment entry uses a mechanism (NU, OU, CC, CD) not allowed by the document type configuration.	Use only the mechanisms listed in the error's `allowedMechanisms` field.
`Payment.ExceedsAmountWithoutChangeAllowed`	400	The delivered amount exceeds the document total and the selected payment type does not allow change.	Use a payment type that allows change, or reduce the delivered amount to match the total.
`Payment.CheckingAccountType.RequiredForMoveSetting`	400	The document type is configured to post to the checking account but the supplied payment type does not.	Use a payment type configured for checking-account posting.
`Payment.CheckingAccountType.RequiredForDeferredMode`	400	The selected payment mode has deferred terms but the payment type does not post to the checking account.	Use a payment type configured for checking-account posting, or choose a non-deferred payment mode.
`Payment.CheckingAccountType.RequiredForDocumentFlow`	400	The document type flow posts to the checking account but the payment type does not.	Use a payment type configured for checking-account posting.
`Payment.CheckingAccount.NotSupported`	400	A checking-account payment type was supplied; this API only supports immediate payments.	Use an immediate payment type (cash, card, cheque, etc.).
`PaymentType.NotFound`	404	No payment type found with the supplied `paymentTypeId`.	Supply a valid `paymentTypeId`.
`PaymentMode.NotFound`	404	No payment mode found with the supplied `paymentModeId`.	Supply a valid `paymentModeId`.

Optional payments

payments is optional when the document type has neither cashier flow nor checking-account flow active (CashierFlow = NoAction, CheckingAccountFlow = None). Transport guides (GT…GD), orders (NE), and quotes (ORC) are typically configured this way. When optional, omit payments entirely or include at most one entry whose amount equals the document total.

Customer / Entity

Code	HTTP	Condition	Resolution
`Entity.KeyId.NotFound`	404	`entityKeyId` was provided but no entity with that key exists in the database.	Correct the `entityKeyId`, or omit it and use `entityVat` to identify the customer.
`Customer.Inactive`	400	The resolved customer is inactive.	Reactivate the customer in the back-office, or use a different customer.
`Customer.ForbiddenDocuments`	400	The customer's account is configured to prevent document issuance.	Remove the restriction in the back-office, or use a different customer.
`Entity.Vat.Invalid`	400	The supplied `entityVat` failed the VAT validation check for the configured country.	Correct the VAT number or omit `entityVat` to use the final-consumer defaults.

Items and Taxes

Code	HTTP	Condition	Resolution
`Item.NotFound`	404	A `documentBodies` line references an `itemKeyId` that does not exist in the catalogue.	Verify the `itemKeyId` values in the body lines.
`Tax.NotFound`	404	A `documentBodies` line references a `taxId` or `secondTaxId` that does not exist.	Supply valid tax identifiers — resolve them with `GET /gateway/tax`.

Document Rules

Code	Condition	Resolution
`SaleDocumentRules.Transport.MissingPlaces`	A transport guide was submitted without a load place, or without an unload place (and the document type is not global).	Populate `loadPlaceDescription` and `unloadPlaceDescription` (or ensure the customer has an address for the fallback).
`SaleDocumentRules.FullInfo.RequiredCustomer`	The document type requires a customer VAT number and none was supplied.	Provide `entityVat` (or a resolved `entityKeyId` whose record has a VAT number).
`SaleDocumentRules.FullInfo.CustomerFiscalData`	The document type requires complete customer fiscal data (name, address, VAT).	Ensure the customer record or the override fields contain full fiscal information.
`SaleDocumentRules.Nif.RequiredVat`	The document amount exceeds the threshold above which a VAT number is legally required.	Supply a valid `entityVat`.
`SaleDocumentRules.NCND.MissingReferences`	A Credit Note (NC) or Debit Note (ND) was submitted without document references in `documentBodies`.	Include at least one `documentReference` in each body line pointing to the origin document.
`SaleDocumentRules.NCND.MissingEmissionReason`	A Credit/Debit Note is missing the mandatory `emissionReason` field (required for PT and AO).	Provide `emissionReason` in the request.
`SaleDocumentRules.LimitExceeded`	The document total exceeds the per-document limit configured in the document type settings.	Reduce the document amount, or increase the limit in the back-office configuration.
`SaleDocumentRules.FS.AboveLegal`	A Simplified Invoice (FS) was issued above the legal threshold defined in Article 40 of the VAT Code.	Issue a full Invoice (FT) instead.

References (NC / ND)

Code	Condition	Resolution
`DocumentReference.OriginBodyNotFound`	A body line reference points to an origin body GUID that does not exist or has been deleted.	Verify the `originBodyGuid` values via `GET /gateway/invoice/invoices/{id}`.
`DocumentReference.BalanceExceeded`	The requested reference quantity plus already-referenced quantity exceeds the original line quantity.	Reduce the quantity on the referencing line so it does not exceed the remaining balance.
`DocumentReference.ItemMismatch`	The supplied `itemKeyId` does not match the origin line's item.	Omit `itemKeyId` or send the same item as the origin.
`DocumentReference.PriceMismatch`	A price was supplied but differs from the origin-derived price on an Angolan rectifying document.	Omit `retailPrice`/`netPrice` or match the original invoiced price.
`DocumentReference.EntityMismatch`	The customer on the NC/ND does not match the customer of the origin document.	Use the same `entityKeyId` as the origin invoice.

Stock

Code	Condition	Resolution
`Stock.InsufficientQuantity`	A document body line references an item with insufficient stock (when the document type deducts stock).	Reduce the quantity, or replenish stock before issuing the document. The `itemKeyId` is included in the error details.

Transaction (500)

These errors indicate a database-level failure during document persistence. The document was not saved. Retrying the request is safe.

Code	Condition
`Transaction.Begin.Failed`	The database transaction could not be opened.
`Transaction.Commit.Failed`	The document pipeline completed successfully but the final commit failed.

Last Updated: July 7, 2026

Document Type​

Payment​

Customer / Entity​

Items and Taxes​

Document Rules​

References (NC / ND)​

Stock​

Transaction (500)​