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 |
|---|---|---|---|
amount_reconciliation_failed | invalid_request_error | 422 | Los importes con IVA incluido no se pueden repartir en líneas que sumen exactamente lo cobrado, así que no se ha emitido nada antes que alterar el total. Lo causa, por ejemplo, una retención o un recargo de equivalencia que mueven el total más que una diferencia de redondeo. |
corrective_client_change_requires_substitution | invalid_request_error | 422 | La rectificativa va a nombre de un cliente distinto del de la factura original (p. ej. por un error en los datos del cliente): solo puede ser una sustitución, porque por diferencias el importe quedaría a nombre de quien no recibió la factura. |
corrective_full_cancellation_with_lines | invalid_request_error | 422 | Anular la factura entera por diferencias (correction_type total, full en la API, con correction_nature: I) no admite líneas: la rectificativa copia en negativo todas las de la original. |
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. |
corrective_substitution_negative_amount | invalid_request_error | 422 | En una rectificativa por sustitución (correction_nature: S, o full con lines sin naturaleza) cada línea lleva el importe FINAL de la factura correcta, así que ninguna cantidad puede ser negativa (art. 15.5 RD 1619/2012; VERI*FACTU no admite base negativa en una sustitución). El precio unitario nunca es negativo: el signo va en la cantidad. |
corrective_substitution_requires_full | invalid_request_error | 422 | Una rectificativa por sustitución (correction_nature: S) sustituye la factura entera; no hay sustitución parcial. |
exemption_cause_contradicts_taxed_lines | invalid_request_error | 422 | La factura lleva una causa de exención de cabecera que declara la operación sin IVA (exención, no sujeción o inversión del sujeto pasivo) y alguna línea de operación tiene un IVA mayor que cero. |
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. |
face_submission_attempt_conflict | conflict_error | 409 | Otra petición modificó el intento de envío a FACe (reserva o conciliación) mientras actuabas sobre él. |
face_submission_completion_failed | api_error | 500 | FACe respondió al envío pero la plataforma no pudo guardar el resultado localmente. |
face_submission_rejected | invalid_request_error | 422 | FACe analizó el envío y lo rechazó con su propio código de error (por ejemplo un código DIR3 erróneo, una firma no válida o un duplicado). A diferencia de una transmisión incierta, FACe no registró la factura. |
face_transmission_uncertain | conflict_error | 409 | La factura se envió a FACe pero se desconoce el resultado, así que FACe puede haberla registrado o no. |
facturae_artifact_unavailable | api_error | 500 | El archivo Facturae conservado para ese envío no se puede leer del almacenamiento porque falta o está dañado. El fallo es nuestro. |
facturae_operation_forbidden | authorization_error | 403 | El actor no puede realizar esa operación de Facturae; details.reason indica si se trata de los permisos del actor, de la autoridad del emisor, del acceso a la factura o del derecho a enviarla. |
invalid_correction_nature | invalid_request_error | 422 | correction_nature solo acepta I (por diferencias: la rectificativa lleva el importe de la rectificación, con su signo) o S (sustitución: lleva la factura tal y como queda, con las líneas finales). |
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_delivery_channel | invalid_request_error | 422 | El canal de envío queda fuera del catálogo, que solo tiene dos valores: email (se registra solo cuando el servidor de correo acepta el mensaje) y manual (un envío que hiciste por tus propios medios). |
invalid_facturae_structured_data | invalid_request_error | 422 | Los datos estructurados necesarios para construir el archivo Facturae no son válidos: un valor es incorrecto, los totales no cuadran con las líneas o el XML generado no cumple el esquema. |
invalid_invoice_business_data | invalid_request_error | 422 | Los datos comerciales de la factura (referencias de línea, centros administrativos o sus roles) contienen un valor no válido. |
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 de numeración de su serie (por defecto SERIE-AAAA-NNN; las rectificativas llevan el número correlativo de su propia serie, p. ej. R-2026-001). |
invalid_invoice_payment_terms | invalid_request_error | 422 | El calendario de pago de la factura incumple una regla, por ejemplo plazos que no suman el total, fechas no válidas o falta la cuenta bancaria contractual. |
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, issued, overdue, cancelled, annulled). Antes de la versión de API 2026-10-01 issued se publica como sent, y allí donde la API lee un estado de entrada (los filtros de estado, el cambio de estado masivo) sent se toma como issued. 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_administrative_precondition_required | invalid_request_error | 428 | El cambio del routing administrativo no indicó sobre qué versión se basa. |
invoice_administrative_version_conflict | conflict_error | 409 | El routing administrativo de la factura (sus centros administrativos) cambió después de leerla. |
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_rectified_in_full | invalid_request_error | 422 | La factura ya está anulada por completo (una rectificativa total por diferencias), y entonces no admite ninguna rectificativa más; o está sustituida por completo, y entonces no admite otra rectificación total. |
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_marked_as_sent | invalid_request_error | 422 | La marca de envío registra que una factura emitida llegó al cliente, así que solo aplica a facturas issued u overdue. Un borrador o una factura programada todavía no son la factura fiscal, y una cancelada o anulada ya no lo es. |
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_due_date_not_last_instalment | invalid_request_error | 422 | La factura tiene plazos de pago y su vencimiento (due_on) falta o no es la fecha del último plazo, que es cuando vence la factura. |
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, issued o cancelled, scheduled vuelve a draft o avanza a issued, issued pasa a overdue o annulled, overdue a annulled, y cancelled y annulled son terminales. El ciclo es el mismo en todas las versiones de API; antes de 2026-10-01 el estado issued se publica como sent. 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, esté cobrada o no: issued u overdue (una factura emitida se publica como sent antes de la versión de API 2026-10-01). Un borrador, una factura programada, una 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 envío solo aplica a una factura emitida (issued u overdue; publicada como sent antes de la versión de API 2026-10-01) sin cobros vigentes: limpia sent_at y sent_via y conserva su estado fiscal. |
invoice_payment_terms_precondition_required | invalid_request_error | 428 | El cambio del calendario de pago no indicó sobre qué versión se basa. |
invoice_payment_terms_version_conflict | conflict_error | 409 | El calendario de pago de la factura cambió después de leerla. |
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_type_change_not_allowed | invalid_request_error | 422 | Solo un borrador alterna entre factura completa (F1) y simplificada (F2). Una rectificativa, una sustitutiva (F3) o una rectificativa de simplificada (R5) conservan su tipo, y una simplificada sin cliente no pasa a completa sin indicar antes el destinatario. |
invoice_without_retained_presentation | invalid_request_error | 422 | Una factura del trimestre no tiene presentación documental retenida (es anterior a la captura o nunca se inicializó), así que no puede incluirse en el paquete trimestral. Aparece como error_code en los failures del manifiesto del ZIP trimestral, donde la factura queda fuera, y como subcódigo de una violación de regla de negocio en el correo trimestral. |
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. |
operation_date_after_issue_date | invalid_request_error | 422 | operation_on es posterior a issued_on. Una fecha de operación posterior a la de expedición solo es válida en pagos anticipados (clave de régimen 14 o 15). |
pack_return_invalid | invalid_request_error | 422 | La devolución de un componente de pack en una factura rectificativa incumple las reglas de devolución. El pack no está en la factura que se rectifica, el producto no es uno de sus componentes, la cantidad no es negativa, el precio difiere del precio repartido original o se devuelven más unidades de las vendidas. |
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 issued ni overdue (una factura emitida se publica como sent antes de la versión de API 2026-10-01), 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_invoices_disabled | invalid_request_error | 422 | La empresa no tiene habilitadas las facturas simplificadas, así que no se puede crear una factura de tipo F2. |
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. |
tax_rate_mismatch | invalid_request_error | 422 | La línea elige un impuesto por id (tax_rate_id, retention_rate_id o surcharge_rate_id) y lo contradice: declara un tax_rate, retention_rate o surcharge_rate distinto del de ese impuesto, o el impuesto es de otra clase que su campo (por ejemplo, una retención en surcharge_rate_id). El IVA elegido califica además la línea (régimen, calificación AEAT y causa de exención), así que los dos datos deben coincidir. |
unattended_replay_mismatch | idempotency_error | 409 | Ya se emitió una factura con ese external_id con otro tipo u otro total, así que la petición no puede tratarse como un reenvío de la misma venta. Se responde con 409, code y subcode unattended_replay_mismatch y param=external_id: el external_id identifica UNA operación y no caduca. No es idempotency_key_reused, el 422 de una Idempotency-Key reutilizada con otro payload. |
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.