Códigos de error de Facturas
Todos los códigos de error de la API pública que emite Facturas, con su estado HTTP, su type y una página por código.
Códigos de error que emite Facturas. Cada code enlaza a su propia página con la causa y la acción a tomar.
| Code | Type | HTTP | Descripción |
|---|---|---|---|
corrective_invoice_inanulable | invalid_request_error | 422 | La factura es a su vez una rectificativa, y las rectificativas nunca se anulan: la cadena de corrección tiene que seguir siendo auditable de punta a punta. |
export_limit_exceeded | invalid_request_error | 422 | La selección filtrada supera el tope de 5.000 facturas de la exportación, así que el fichero se rechaza de entrada en lugar de truncarse en silencio. |
invalid_correction_nature | invalid_request_error | 422 | correction_nature solo acepta S (sustitución: la rectificativa lleva los importes corregidos completos) o I (por diferencias: lleva solo el delta). |
invalid_correction_reason | invalid_request_error | 422 | El motivo de rectificación queda fuera de la lista fiscal cerrada (error_fundado, concurso, incobrable, error_importe, error_cliente, devolucion, descuento, otras), que mapea a los códigos AEAT R1 a R4. |
invalid_invoice_id | invalid_request_error | 400 | La referencia de factura recibida no es un identificador válido; suele significar que se coló un valor interno donde la API espera el id público. |
invalid_invoice_number | invalid_request_error | 422 | El número de factura no sigue el formato canónico SERIE-AAAA-NNN, más el sufijo -RECn en las rectificativas. |
invalid_invoice_status | invalid_request_error | 422 | El valor enviado como estado de factura queda fuera del catálogo del ciclo de vida documental (draft, scheduled, sent, overdue, cancelled, annulled). paid es un valor válido para leer y para filtrar, pero no para escribir: registra un cobro en su lugar. |
invalid_invoice_uuid | invalid_request_error | 400 | El identificador de factura de la ruta o del payload no es un UUID válido. |
invalid_payment_method | invalid_request_error | 422 | El método de pago queda fuera de la allowlist cerrada: bank_transfer, cash, credit_card, sepa_direct_debit, paypal, bizum, other. |
invoice_already_annulled | invalid_request_error | 422 | La factura ya estaba anulada. La anulación es terminal y, con VeriFactu activo, su registro de anulación ya llegó a la AEAT. |
invoice_already_paid | invalid_request_error | 422 | La factura ya está cobrada. paid es un estado terminal y contablemente cerrado: el IVA repercutido ya se ha declarado, o se declarará en el período. |
invoice_already_sent | invalid_request_error | 422 | La factura ya fue emitida: tiene número definitivo de serie y, con VeriFactu activo, su alta en la AEAT. La emisión no ocurre dos veces. |
invoice_cannot_assign_number | invalid_request_error | 422 | Se pidió número definitivo para una factura que no es borrador, o que ya lo tiene. La numeración de serie es monótona y los números no se reasignan. |
invoice_cannot_be_sent | invalid_request_error | 422 | La factura está anulada o cancelada: ya no representa una operación válida, así que su PDF no se entrega al destinatario. |
invoice_invalid_status_transition | invalid_request_error | 422 | El estado destino no es alcanzable desde el actual. El ciclo de vida documental es dirigido: draft pasa a scheduled o sent, sent a overdue o annulled, overdue a annulled, y cancelled y annulled son terminales. Estar cobrada no es un paso de ese ciclo: se lee del ledger de cobros. |
invoice_not_cancellable_in_current_state | invalid_request_error | 422 | Cancelar retira un borrador que todavía no es fiscalmente vinculante, así que solo aplica mientras la factura está en draft. |
invoice_not_correctable_in_current_state | invalid_request_error | 422 | Una rectificativa solo se emite contra una factura ya emitida (sent o paid). Un borrador, una factura cancelada o una anulada no tienen nada que rectificar. |
invoice_not_deletable_in_current_state | invalid_request_error | 422 | Solo se borran las facturas en draft y cancelled. Una factura numerada nunca desaparece: la serie correlativa debe seguir siendo auditable. |
invoice_not_editable_in_current_state | invalid_request_error | 422 | Solo un borrador admite edición. Una vez emitida, la factura es inmutable y su contenido queda congelado junto con su registro fiscal. |
invoice_not_eligible_for_action | invalid_request_error | 422 | La acción solicitada no aplica a esta factura: su tipo o su estado actual la dejan fuera del alcance de la operación. |
invoice_not_found | not_found_error | 404 | El identificador no resuelve a ninguna factura de la empresa autenticada. Las facturas de otra empresa responden exactamente igual. |
invoice_not_modifiable_in_current_state | invalid_request_error | 422 | El campo que intentas cambiar está congelado para el estado actual — por ejemplo el régimen fiscal de una factura anulada. |
invoice_not_paid | invalid_request_error | 422 | Se pidió un justificante de pago de una factura sin cobro registrado, así que no hay nada que certificar. |
invoice_not_reschedulable_in_current_state | invalid_request_error | 422 | Reprogramar mueve la fecha de emisión de una factura que está esperando en scheduled, y esta factura no está esperando. |
invoice_not_schedulable_in_current_state | invalid_request_error | 422 | Solo un borrador se puede programar: la programación reserva un momento futuro de emisión sin consumir todavía número de serie. |
invoice_not_unschedulable_in_current_state | invalid_request_error | 422 | Desprogramar devuelve la factura de scheduled a draft, así que solo aplica mientras sigue esperando a emitirse. |
invoice_not_unsendable_in_current_state | invalid_request_error | 422 | Deshacer la marca de entrega solo aplica a una factura sent: limpia sent_at y mantiene la factura emitida. |
invoice_requires_at_least_one_line | invalid_request_error | 422 | La factura no lleva ninguna línea de operación, así que no tiene base imponible y no se puede emitir. Ocurre cuando no envías líneas y cuando todas las que envías son de suplido: un suplido es una cantidad pagada por cuenta del cliente (art. 78.Tres.3 LIVA), no una operación tuya. |
invoice_year_required_for_ambiguous_number | invalid_request_error | 422 | Ese número de factura corresponde a más de una factura, así que por sí solo no identifica ninguna. Se repite por dos motivos independientes: el ejercicio (las series reciclan la numeración cada año) y la serie (dos series de tu empresa emiten cada una su propio F-2026-001). |
line_total_checksum_mismatch | invalid_request_error | 422 | El line_total declarado no coincide con el que calcula Factuarea para esa línea (cantidad × precio − descuento + IVA − retención + recargo) y la desviación supera el céntimo de tolerancia. El importe que se factura y se declara a la AEAT es siempre el calculado aquí, así que la discrepancia significa que tu sistema y la factura emitida no cuadrarían. |
line_type_invalid | invalid_request_error | 422 | El tipo de línea queda fuera del catálogo cerrado NORMAL / SUPLIDO. Una factura emitida sólo distingue dos naturalezas: lo que vendes tú, que forma base imponible y lleva IVA, y el suplido, que es dinero adelantado en nombre y por cuenta del cliente y por eso queda fuera de la base (art. 78.Tres.3 LIVA). |
no_invoices_in_period | invalid_request_error | 422 | La operación trimestral no encontró facturas en el período pedido, así que no hay nada que empaquetar ni enviar. |
payment_method_invalid | invalid_request_error | 422 | La misma allowlist cerrada que invalid_payment_method, reportada cuando el valor se rechaza al leer el campo de método de pago del payload. |
rectified_invoice_inanulable | invalid_request_error | 422 | Esta factura ya tiene una rectificativa total (correction_type: full), que devolvió su importe y su mercancía. Anularla ahora los devolvería por segunda vez. Una rectificativa parcial no bloquea: la factura sigue viva y su anulación es legítima. |
reminder_not_applicable | invalid_request_error | 422 | El recordatorio de pago no procede: la factura no está en sent ni overdue, no hay email de destinatario, falta el enlace público o está desactivado, o ya salió otro recordatorio en las últimas 24 horas. |
scheduled_for_in_past | invalid_request_error | 422 | scheduled_for no es estrictamente futuro, así que no hay ninguna espera que reservar. |
simplified_invoice_cannot_be_substituted | invalid_request_error | 422 | Una de las facturas de la lista de sustitución no se puede sustituir: no es simplificada, está cancelada o anulada, pertenece a otra empresa, o ya tiene sustitutiva. |
simplified_invoice_not_allowed | invalid_request_error | 422 | La operación no es elegible para factura simplificada: supera los 3.000 €, o es una entrega intracomunitaria, una exportación, una operación con inversión del sujeto pasivo, o el cliente necesita factura completa para deducir el IVA. |
simplified_limit_exceeded | invalid_request_error | 422 | Las líneas llevarían la factura simplificada (F2) por encima del tope legal absoluto de 3.000 € IVA incluido. |
suplido_line_cannot_carry_taxes | invalid_request_error | 422 | La línea de suplido lleva carga propia: tipo de IVA, retención, recargo de equivalencia, descuento, clave de régimen, causa de exención o producto/pack. Un suplido no es una operación del emisor, así que repercutir un impuesto sobre él sería tributar por una entrega que no has hecho, y ligarlo a un producto movería un stock que nunca has vendido. |
suplido_not_allowed_in_simplified_invoice | invalid_request_error | 422 | La factura es simplificada (F2) y una simplificada no identifica al destinatario. Sin destinatario identificado no hay a quién acreditar el pago por cuenta ajena, así que el importe no admite el tratamiento de suplido en este tipo de factura. |
suplido_requires_source_invoice_reference | invalid_request_error | 422 | La línea de suplido no informa source_invoice_reference, el número del justificante que el tercero expidió a nombre del cliente. Sin ese justificante el pago no se acredita como hecho por cuenta ajena y Hacienda lo trataría como base imponible propia del emisor, con su IVA repercutido. |
Relacionado
Códigos de error por categoría
Localiza un error por la categoría que lo emite.
Tabla de referencia completa
Todos los códigos, estados HTTP, tipos y descripciones en una referencia.
Modelo de errores
Interpreta la respuesta de error y gestiona los errores por código.