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.CannotMixWithImmediatePayments`	400	The document mixes checking-account payments with immediate payments.	Settle fully with immediate payments, or post the full amount to the checking account.
`Payment.CheckingAccount.NotAllowedForInvoiceReceipt`	400	An invoice-receipt (FR) was submitted with a checking-account payment type.	Use an immediate payment type for FR documents.
`Payment.CheckingAccount.CustomerRequired`	400	Checking-account or deferred payment was used without a specifically identified customer.	Supply a resolved customer (`entityKeyId` / `entityVat`), not the final consumer.
`Payment.CheckingAccount.NotAllowedForCashierMoveSetting`	400	The document type is configured for cashier movement and cannot be paid through the checking account.	Use an immediate payment type, or a document type that allows checking-account posting.
`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.

Cashier / Business account

Code	HTTP	Condition	Resolution
`Cashier.BusinessAccount.NotFound`	404	The top-level `businessAccountId` was supplied but no business account with that id exists.	Supply a valid `businessAccountId`, or omit it / send `0` to use the default cashier resolution.
`BusinessAccount.OpenCashier.ManualOpening`	400	The selected cashier requires manual opening and has no open session.	Open the cashier session in the back-office/treasury UI, then retry.
`BusinessAccount.OpenCashier.RequestOpening`	400	The selected cashier requires opening on demand and has no open session.	Open the cashier session (WebClient shows the open-cashier dialog), then retry.
`BusinessAccount.Access.Unauthorized`	401	The cashier is password-protected and the caller is neither the owner nor holding a valid authorize token.	Call `POST /gateway/business-account/{id}/authorize` and retry with cookie `BAAuthToken` or header `X-BA-Auth-Token`.
`BusinessAccount.Access.UserIsNotInPermissionList`	403	The user is not allowed to operate the selected business account.	Use an account the user can access, or update the account permission list.

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.

Customer credit

Customer credit validation can block issuance (errors below) or emit non-blocking warnings on a successful 201 response (warnings[] on CreateDocumentResponse).

Code	HTTP	Condition	Resolution
`CustomerCredit.Limit.AmountExceeded`	400	The document would exceed the customer's credit amount limit. `furtherInformations` includes balances/limits and `canOverride`.	Reduce the amount, settle the account, or — if `canOverride` is `true` and the caller is an administrator — resubmit with `allowCreditLimitOverride: true`.
`CustomerCredit.Limit.OverdueDocuments`	400	The customer has unpaid sale documents beyond the configured due-days limit. `furtherInformations` may include overdue document details and `canOverride`.	Collect overdue documents, or — if allowed — resubmit with `allowCreditLimitOverride: true` as an administrator.
`CustomerCredit.Header.Missing`	500	The document header was not available for credit validation.	Retry; if it persists, contact support.
`CustomerCredit.Customer.Missing`	500	The customer was not available for credit validation.	Ensure the entity resolves correctly (`entityKeyId` / `entityVat`).
`CustomerCredit.Validation.Failed`	500	Credit limit validation failed unexpectedly.	Retry; if it persists, contact support.

Non-blocking warnings (returned in warnings[], document still created):

Code	Meaning
`CustomerCredit.Alert.AmountExceeded`	The document exceeded the customer credit alert threshold (soft warning).
`CustomerCredit.Limit.Overridden`	An administrator explicitly overrode an exceeded credit limit via `allowCreditLimitOverride: true`.

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​

Cashier / Business account​

Customer / Entity​

Items and Taxes​

Document Rules​

Customer credit​

References (NC / ND)​

Stock​

Transaction (500)​