Factuarea API

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
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.
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.
invalid_correction_natureinvalid_request_error422correction_nature only accepts S (substitution: the corrective carries the full corrected amounts) or I (by difference: it carries only the delta).
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_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 canonical format SERIES-YYYY-NNN, plus the -RECn suffix on correctives.
invalid_invoice_statusinvalid_request_error422The value sent as invoice status is outside the lifecycle catalogue (draft, scheduled, sent, paid, overdue, cancelled, annulled).
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_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_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_invalid_status_transitioninvalid_request_error422The target status is unreachable from the current one. The lifecycle is directed: draft moves to scheduled or sent, sent to paid, overdue or annulled, and paid, cancelled and annulled are terminal.
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 (sent or paid). A draft, 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 a sent invoice: it clears sent_at and keeps the invoice issued.
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_year_required_for_ambiguous_numberinvalid_request_error422That invoice number exists in more than one fiscal year, so on its own it does not identify a single invoice.
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.
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.
reminder_not_applicableinvalid_request_error422The payment reminder does not apply: the invoice is not sent or overdue, 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_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.

All error codes

Quotes error codes

On this page

Related