Factuarea APIDevelopers
Support
Open app

Invoices error codes

Every public API error code emitted by Invoices, with its HTTP status, its type and a page per code.

Error codes emitted by Invoices. Each code links to its own page with the cause and the action to take.

CodeTypeHTTPDescription
amount_reconciliation_failedinvalid_request_error422The amounts with VAT included cannot be split into line amounts that add up to exactly the amount charged, so nothing was issued rather than alter the total. A withholding or an equivalence surcharge that moves the total by more than a rounding difference causes it.
corrective_client_change_requires_substitutioninvalid_request_error422The corrective is issued to a client other than the original invoice's (for instance, after an error in the client data): it can only be a substitution, because by differences the amount would be attributed to someone who never received the invoice.
corrective_full_cancellation_with_linesinvalid_request_error422Voiding the whole invoice by differences (correction_type: full with correction_nature: I) takes no lines: the corrective copies every original line back negated.
corrective_invoice_inanulableinvalid_request_error422The invoice is itself a corrective, and correctives are never annulled: the correction chain has to stay auditable end to end.
corrective_substitution_negative_amountinvalid_request_error422In a substitution corrective (correction_nature: S, or full with lines and no nature) each line carries the FINAL amount of the correct invoice, so no quantity can be negative (art. 15.5 RD 1619/2012; VERI*FACTU does not accept a negative base in a substitution). The unit price is never negative: the sign goes in the quantity.
corrective_substitution_requires_fullinvalid_request_error422A substitution corrective (correction_nature: S) replaces the whole invoice; there is no partial substitution.
exemption_cause_contradicts_taxed_linesinvalid_request_error422The invoice carries a header exemption cause that declares the operation VAT-free (exemption, non-subject or reverse charge) and an operation line has a VAT rate above zero.
export_limit_exceededinvalid_request_error422The filtered selection exceeds the 5,000-invoice cap of the export, so the file is refused up front instead of being silently truncated.
face_submission_attempt_conflictconflict_error409Another request changed the FACe submission attempt (claim or reconciliation) while you were acting on it.
face_submission_completion_failedapi_error500FACe answered the submission but the platform could not store the result locally.
face_submission_rejectedinvalid_request_error422FACe analysed the submission and rejected it with its own error code (for example a wrong DIR3 code, an invalid signature or a duplicate). Unlike an uncertain transmission, FACe did not register the invoice.
face_transmission_uncertainconflict_error409The invoice was sent to FACe but its outcome is unknown, so FACe may or may not have registered it.
facturae_artifact_unavailableapi_error500The Facturae file retained for that submission cannot be read from storage because it is missing or damaged. The failure is on our side.
facturae_operation_forbiddenauthorization_error403The actor cannot perform that Facturae operation; details.reason tells whether it is a matter of the actor's permissions, the issuer's authority, access to the invoice or the right to send it.
invalid_correction_natureinvalid_request_error422correction_nature only accepts I (by differences: the corrective carries the amount of the rectification, with its sign) or S (substitution: it carries the invoice as it ends up, with the final lines).
invalid_correction_reasoninvalid_request_error422The correction reason is outside the closed fiscal list (error_fundado, concurso, incobrable, error_importe, error_cliente, devolucion, descuento, otras), which maps to the AEAT codes R1 to R4.
invalid_delivery_channelinvalid_request_error422The delivery channel is outside the catalogue, which has only two values: email (recorded automatically when the mail server accepts the message) and manual (a delivery you made by your own means).
invalid_facturae_structured_datainvalid_request_error422The structured data needed to build the Facturae file is not valid: a value is wrong, the totals do not match the lines, or the generated XML fails the schema.
invalid_invoice_business_datainvalid_request_error422The business data of the invoice (line references, administrative centres or their roles) contains an invalid value.
invalid_invoice_idinvalid_request_error400The invoice reference received is not a valid identifier; it usually means an internal value slipped in where the API expects the public id.
invalid_invoice_numberinvalid_request_error422The invoice number does not follow the numbering format of its series (by default SERIES-YYYY-NNN; correctives carry the correlative number of their own series, e.g. R-2026-001).
invalid_invoice_payment_termsinvalid_request_error422The payment schedule of the invoice breaks a rule, for example installments that do not add up to the total, invalid dates or a missing contractual bank account.
invalid_invoice_statusinvalid_request_error422The value sent as invoice status is outside the document lifecycle catalogue (draft, scheduled, issued, overdue, cancelled, annulled). Before API version 2026-10-01 issued is published as sent, and wherever the API reads a status as input (the status filters, the bulk status change) sent is taken as issued. paid is a valid value to read and to filter by, but not to write: register a payment instead.
invalid_invoice_uuidinvalid_request_error400The invoice identifier in the path or in the payload is not a valid UUID.
invalid_payment_methodinvalid_request_error422The payment method is outside the closed allowlist: bank_transfer, cash, credit_card, sepa_direct_debit, paypal, bizum, other.
invoice_administrative_precondition_requiredinvalid_request_error428The change to the administrative routing did not state which version it is based on.
invoice_administrative_version_conflictconflict_error409The administrative routing of the invoice (its administrative centres) changed after you read it.
invoice_already_annulledinvalid_request_error422The invoice was already annulled. Annulment is terminal and, with VeriFactu active, its annulment record has already reached AEAT.
invoice_already_paidinvalid_request_error422The invoice is already settled. paid is a terminal, accounting-closed state: the output VAT has been declared, or will be declared for the period.
invoice_already_rectified_in_fullinvalid_request_error422The invoice is already voided in full (a full corrective by differences), so it admits no further corrective; or it is replaced in full, so it admits no second full correction.
invoice_already_sentinvalid_request_error422The invoice was already issued: it holds a definitive series number and, with VeriFactu active, its registration with AEAT. Issuing does not happen twice.
invoice_cannot_assign_numberinvalid_request_error422A definitive number was requested for an invoice that is not a draft, or that already carries one. Series numbering is monotonic and numbers are never reassigned.
invoice_cannot_be_marked_as_sentinvalid_request_error422The delivery mark records that an issued invoice reached the customer, so it only applies to issued or overdue invoices. A draft or a scheduled invoice is not the fiscal invoice yet, and a cancelled or annulled one no longer is.
invoice_cannot_be_sentinvalid_request_error422The invoice is voided or cancelled: it no longer represents a valid operation, so its PDF is not delivered to the recipient.
invoice_due_date_not_last_instalmentinvalid_request_error422The invoice has a payment schedule and its due date (due_on) is missing or is not the date of the last installment, which is when the invoice falls due.
invoice_invalid_status_transitioninvalid_request_error422The target status is unreachable from the current one. The document lifecycle is directed: draft moves to scheduled, issued or cancelled, scheduled back to draft or on to issued, issued to overdue or annulled, overdue to annulled, and cancelled and annulled are terminal. The lifecycle is the same in every API version; before 2026-10-01 the issued status is published as sent. Being paid is not a step of that lifecycle: it is read from the payment ledger.
invoice_not_cancellable_in_current_stateinvalid_request_error422Cancelling withdraws a draft that is not yet fiscally binding, so it only applies while the invoice is draft.
invoice_not_correctable_in_current_stateinvalid_request_error422A corrective invoice can only be issued against an invoice that is already issued, paid or not: issued or overdue (an issued invoice is published as sent before API version 2026-10-01). A draft, a scheduled, a cancelled or an annulled invoice has nothing to correct.
invoice_not_deletable_in_current_stateinvalid_request_error422Only draft and cancelled invoices can be deleted. A numbered invoice never disappears: the correlative sequence must stay auditable.
invoice_not_editable_in_current_stateinvalid_request_error422Only a draft admits editing. Once issued, the invoice is immutable and its content is frozen along with its fiscal record.
invoice_not_eligible_for_actioninvalid_request_error422The requested action does not apply to this invoice: its type or its current state leaves it outside the scope of the operation.
invoice_not_foundnot_found_error404The identifier does not resolve to any invoice of the authenticated company. Invoices belonging to another company answer exactly the same way.
invoice_not_modifiable_in_current_stateinvalid_request_error422The field you are changing is frozen for the current state — for instance the tax regime of an annulled invoice.
invoice_not_paidinvalid_request_error422A payment receipt was requested for an invoice with no settled payment, so there is nothing to certify.
invoice_not_reschedulable_in_current_stateinvalid_request_error422Rescheduling moves the issuing date of an invoice that is waiting in scheduled, and this invoice is not waiting.
invoice_not_schedulable_in_current_stateinvalid_request_error422Only a draft can be scheduled: scheduling reserves a future issuing moment without consuming a series number yet.
invoice_not_unschedulable_in_current_stateinvalid_request_error422Unscheduling returns an invoice from scheduled to draft, so it only applies while it is still waiting to be issued.
invoice_not_unsendable_in_current_stateinvalid_request_error422Undoing the delivery mark only applies to an issued invoice (issued or overdue; published as sent before API version 2026-10-01) with no active payments: it clears sent_at and sent_via and keeps its fiscal status.
invoice_payment_terms_precondition_requiredinvalid_request_error428The change to the payment schedule did not state which version it is based on.
invoice_payment_terms_version_conflictconflict_error409The payment schedule of the invoice changed after you read it.
invoice_requires_at_least_one_lineinvalid_request_error422The invoice carries no operation line, so it has no taxable base and cannot be issued. This happens both when you send no lines at all and when every line you send is a disbursement: a disbursement is an amount paid on the customer's behalf (art. 78.Tres.3 LIVA), not an operation of your own.
invoice_type_change_not_allowedinvalid_request_error422Only a draft can switch between a complete invoice (F1) and a simplified one (F2). A corrective invoice, a substitute invoice (F3) or a corrective invoice of a simplified one (R5) keep their type, and a simplified invoice without a client cannot become a complete one until you set the recipient.
invoice_without_retained_presentationinvalid_request_error422An invoice of the quarter has no retained document presentation (it predates capture or was never initialized), so it cannot be included in the quarterly package. It appears as error_code in the failures of the quarterly ZIP manifest, where the invoice is left out, and as the subcode of a business rule violation in the quarterly email.
invoice_year_required_for_ambiguous_numberinvalid_request_error422That invoice number matches more than one invoice, so on its own it identifies none. It repeats for two independent reasons: the fiscal year (series recycle numbering every year) and the series (two series of your company each issue their own F-2026-001).
line_total_checksum_mismatchinvalid_request_error422The line_total you declared does not match the one Factuarea computes for that line (quantity × price − discount + VAT − withholding + surcharge) and the deviation is above the one-cent tolerance. The amount that gets invoiced and reported to the tax authority is always the one computed here, so the discrepancy means your system and the issued invoice would not reconcile.
line_type_invalidinvalid_request_error422The line type falls outside the closed NORMAL / SUPLIDO catalogue. An issued invoice only tells two natures apart: what you sell, which forms the taxable base and carries VAT, and a disbursement (suplido), money advanced in the name and on behalf of the customer, which is therefore left out of the base (art. 78.Tres.3 of the Spanish VAT Act).
no_invoices_in_periodinvalid_request_error422The quarterly operation found no invoices in the requested period, so there is nothing to package or send.
operation_date_after_issue_dateinvalid_request_error422operation_on is later than issued_on. An operation date after the issue date is only valid for advance payments (regime key 14 or 15).
pack_return_invalidinvalid_request_error422The return of a pack component in a corrective invoice breaks the rules of returns. The pack is not in the invoice being corrected, the product is not one of its components, the quantity is not negative, the price differs from the original split price or more units are returned than were sold.
payment_method_invalidinvalid_request_error422Same closed allowlist as invalid_payment_method, reported when the value is rejected while reading the payment method field of the payload.
rectified_invoice_inanulableinvalid_request_error422This invoice already has a full corrective (correction_type: full), which returned its amount and its goods. Annulling it now would return both a second time. A partial corrective does not block: the invoice stays alive and annulling it is legitimate.
reminder_not_applicableinvalid_request_error422The payment reminder does not apply: the invoice is not issued or overdue (an issued invoice is published as sent before API version 2026-10-01), there is no recipient email, the public link is missing or disabled, or another reminder went out in the last 24 hours.
scheduled_for_in_pastinvalid_request_error422scheduled_for is not strictly in the future, so there is no waiting period to reserve.
simplified_invoice_cannot_be_substitutedinvalid_request_error422One invoice of the substitution list cannot be replaced: it is not simplified, it is cancelled or annulled, it belongs to another company, or it already has a substitute.
simplified_invoice_not_allowedinvalid_request_error422The operation is not eligible for a simplified invoice: it exceeds EUR 3,000, or it is an intra-EU supply, an export, a reverse-charge operation, or the customer needs a full invoice to deduct VAT.
simplified_invoices_disabledinvalid_request_error422The company has not enabled simplified invoices, so an invoice of type F2 cannot be created.
simplified_limit_exceededinvalid_request_error422The lines would push the simplified invoice (F2) over the absolute legal cap of EUR 3,000 VAT included.
suplido_line_cannot_carry_taxesinvalid_request_error422The disbursement line carries charges of its own: a VAT rate, withholding, equivalence surcharge, discount, regime key, exemption cause or product/pack. A disbursement is not an operation of the issuer, so charging tax on it would mean paying tax on a supply you never made, and tying it to a product would move stock you never sold.
suplido_not_allowed_in_simplified_invoiceinvalid_request_error422The invoice is simplified (F2) and a simplified invoice does not identify the recipient. With no identified recipient there is nobody to evidence the payment on behalf of, so the amount cannot take disbursement treatment on this invoice type.
suplido_requires_source_invoice_referenceinvalid_request_error422The disbursement line does not carry source_invoice_reference, the number of the supporting document the third party issued in the customer's name. Without that document the payment is not evidenced as made on someone else's behalf, and the tax authority would treat it as the issuer's own taxable base, with VAT charged on it.
tax_rate_mismatchinvalid_request_error422The line chooses a tax by id (tax_rate_id, retention_rate_id or surcharge_rate_id) and contradicts it: it declares a tax_rate, retention_rate or surcharge_rate different from that tax's rate, or the tax is of another class than its field (for example a withholding tax in surcharge_rate_id). The chosen VAT tax also qualifies the line (regime, AEAT qualification and exemption reason), so both values must match.
unattended_replay_mismatchidempotency_error409An invoice with that external_id was already issued with a different type or total, so the request cannot be treated as a resend of the same sale. It is answered with 409, code and subcode unattended_replay_mismatch and param=external_id: the external_id identifies ONE operation and does not expire. It is not idempotency_key_reused, the 422 of an Idempotency-Key reused with a different payload.
Error codes by category
Find an error by the category that emits it.
Full reference table
All codes, HTTP statuses, types and descriptions in one reference.
Error model
Interpret the error envelope and handle errors by code.
Previous

Integrations

Every public API error code emitted by Integration, with its HTTP status, its type and a page per code.

Next

MCP

Every public API error code emitted by MCP, with its HTTP status, its type and a page per code.

On this page

Related
Need a hand?Contact support