Factuarea API

Todos los error codes

Referencia completa de cada error code de la API pública, agrupado por bounded context, con su estado HTTP y type.

Esta es la referencia canónica de todos los code de error que puede devolver la API pública, agrupados por el bounded context que los emite. Cada code es estable entre versiones; el message es solo para mostrar. El total y la agrupación se generan del catálogo en vivo.

Cuenta

CodeTypeHTTPDescripción
account_not_foundnot_found_error404No se pudo resolver la cuenta asociada a la clave, lo que suele significar que la clave ya no apunta a una empresa viva.
api_key_already_revokedinvalid_request_error422La clave ya estaba revocada, y una clave revocada no admite más operaciones: la revocación es terminal.
api_key_not_foundnot_found_error404El identificador no corresponde a ninguna API key de la empresa autenticada.

Autenticación

CodeTypeHTTPDescripción
api_key_expiredauthentication_error401La clave pasó su fecha de caducidad.
api_key_revokedauthentication_error401La clave fue revocada, y una clave revocada no vuelve a autenticar nunca: revocar es justamente la forma de cortar una credencial filtrada.
invalid_api_keyauthentication_error401La clave no corresponde a ninguna clave activa. Puede estar mal copiada, truncada, o pertenecer a otro entorno: las claves de prueba y las de producción no son intercambiables.
ip_not_allowedauthentication_error401La clave restringe las direcciones que acepta, y la petición llegó desde una que no está en esa lista.
missing_api_keyauthentication_error401La petición no lleva credenciales: ni cabecera Authorization ni X-API-Key.
origin_not_allowedauthentication_error401La petición viene de un origen de navegador que la clave no acepta.
too_many_auth_failuresauthentication_error429Llegaron demasiados intentos fallidos de autenticación desde la misma dirección, así que queda bloqueada temporalmente para frenar los intentos de adivinar credenciales.

Autorización

CodeTypeHTTPDescripción
addon_not_activeauthorization_error403La funcionalidad pertenece a un add-on que ahora mismo no está activo para la empresa.
feature_not_available_in_planauthorization_error403La funcionalidad no está incluida en el plan de la empresa.
forbidden_actionauthorization_error403La acción está bloqueada para este recurso aunque el scope sea el correcto: el recurso pertenece a un catálogo compartido, o el cambio va por otro endpoint.
insufficient_scopeauthorization_error403La clave autentica correctamente pero no lleva el scope que exige esta operación. Los scopes se conceden al emitir la clave y no se amplían en tiempo de llamada.
max_api_keys_exceededauthorization_error422La empresa alcanzó el número de API keys que permite su plan.
max_webhook_endpoints_exceededauthorization_error422La empresa alcanzó el número de endpoints de webhook que permite su nivel de add-on.
module_not_available_in_sandboxauthorization_error403El recurso pertenece a un módulo vetado en modo test. La sandbox nunca toca AEAT, bancos ni cobros reales, así que esos módulos quedan fuera a propósito.
scope_not_allowed_by_planauthorization_error422Uno de los scopes pedidos pertenece a un módulo que el plan no incluye, así que la clave nacería con un permiso que nunca podría ejercer.
scope_not_allowed_in_sandboxauthorization_error422Una clave de prueba no puede nacer con scopes de módulos vetados en sandbox.

Clientes

CodeTypeHTTPDescripción
alternative_id_type_invalidinvalid_request_error422El tipo de identificador alternativo queda fuera del catálogo nif_iva, passport, country_id, residence_certificate, other_document, not_registered.
cannot_have_both_tax_id_and_alternative_idinvalid_request_error422El cliente envía tax_id y un identificador alternativo a la vez. La identidad fiscal es una: el identificador alternativo existe precisamente para partes sin NIF español.
census_requires_tax_idinvalid_request_error422La verificación censal contrasta el par nombre + NIF contra la AEAT, y falta uno de los dos.
client_has_documentsinvalid_request_error422El cliente está referenciado por documentos emitidos. Borrarlo dejaría facturas, presupuestos o albaranes sin la parte a la que se emitieron, y los registros fiscales tienen que seguir siendo trazables.
client_import_too_largeinvalid_request_error422El CSV supera el límite de filas que admite la importación síncrona, ya que el fichero entero se procesa dentro de la propia petición.
client_not_foundnot_found_error404El identificador no resuelve a ningún cliente de la empresa autenticada.
client_requires_tax_identityinvalid_request_error422El cliente no tiene identidad fiscal: ni tax_id ni identificador alternativo, y no se puede emitir una factura a una parte sin identificar.
direct_debit_requires_default_bank_accountinvalid_request_error422Se eligió domiciliación bancaria como método de pago, pero el cliente no tiene cuenta bancaria por defecto a la que cargar.
tax_id_already_existsconflict_error409Otro cliente de la empresa ya tiene ese NIF, y el NIF identifica a la parte sin ambigüedad dentro de una empresa.

Empresas

CodeTypeHTTPDescripción
company_inactiveauthorization_error403El perfil que indica X-Active-Profile es una de tus empresas gestionadas, pero está desactivada y no se puede operar hasta que vuelva a estar activa.
gestoria_module_requiredauthorization_error403La gestoría tiene un plan vigente, pero sin el módulo de gestoría, así que no puede crear ni operar empresas gestionadas.
gestoria_plan_requiredpayment_required_error402La gestoría no tiene una suscripción de pago activa, así que no hay suscripción sobre la que cobrar el asiento.
payment_method_requiredpayment_required_error402Dar de alta una empresa gestionada cobra un asiento de inmediato, y la gestoría opera en modo real sin método de pago configurado.
seat_charge_failedpayment_required_error402El cobro inmediato del prorrateo del asiento fue rechazado: la tarjeta se denegó, necesita autenticación, o el proveedor de pago estaba inaccesible. La empresa no se crea si el asiento no se cobra.

Albaranes

CodeTypeHTTPDescripción
delivery_note_not_foundnot_found_error404El identificador no resuelve a ningún albarán de la empresa autenticada.
delivery_note_section_not_editable_in_statusinvalid_request_error422La sección logística —transportista, vehículo, conductor— está congelada porque el albarán ya está entregado, facturado o cancelado.
driver_tax_id_requires_nameinvalid_request_error422Se envió el NIF del conductor sin su nombre, y un identificador sin nombre no identifica a nadie en el documento de entrega.
signature_payload_too_largeinvalid_request_error422La imagen de la firma supera el tamaño admitido para el campo.

Empleados

CodeTypeHTTPDescripción
employee_seat_charge_failedpayment_required_error402El cobro inmediato del prorrateo del asiento de empleado fue rechazado: la tarjeta se denegó, necesita autenticación, o el proveedor de pago estaba inaccesible. El empleado no se activa si el asiento no se cobra.
employee_seat_payment_method_requiredpayment_required_error402Dar de alta o reactivar un empleado cobra un asiento de inmediato, y la empresa opera en modo real sin método de pago configurado.

Events

CodeTypeHTTPDescripción
event_not_foundnot_found_error404El identificador no corresponde a ningún evento de la empresa autenticada, o el evento fue purgado por la política de retención de 30 días.

Idempotency

CodeTypeHTTPDescripción
idempotency_key_in_useidempotency_error409Hay otra petición con la misma Idempotency-Key todavía en curso, y aún no se conoce su resultado.
idempotency_key_invalidinvalid_request_error400La Idempotency-Key no encaja con el formato admitido: entre 1 y 255 caracteres ASCII imprimibles.
idempotency_key_reusedidempotency_error409Esa Idempotency-Key ya se usó con un payload distinto. La clave identifica una operación concreta, así que reutilizarla para otra vaciaría de sentido el replay.

Facturas

CodeTypeHTTPDescripción
corrective_invoice_inanulableinvalid_request_error422La 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_exceededinvalid_request_error422La 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_natureinvalid_request_error422correction_nature solo acepta S (sustitución: la rectificativa lleva los importes corregidos completos) o I (por diferencias: lleva solo el delta).
invalid_correction_reasoninvalid_request_error422El 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_idinvalid_request_error400La 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_numberinvalid_request_error422El número de factura no sigue el formato canónico SERIE-AAAA-NNN, más el sufijo -RECn en las rectificativas.
invalid_invoice_statusinvalid_request_error422El valor enviado como estado de factura queda fuera del catálogo del ciclo de vida (draft, scheduled, sent, paid, overdue, cancelled, annulled).
invalid_invoice_uuidinvalid_request_error400El identificador de factura de la ruta o del payload no es un UUID válido.
invalid_payment_methodinvalid_request_error422El método de pago queda fuera de la allowlist cerrada: bank_transfer, cash, credit_card, sepa_direct_debit, paypal, bizum, other.
invoice_already_annulledinvalid_request_error422La 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_paidinvalid_request_error422La 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_sentinvalid_request_error422La 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_numberinvalid_request_error422Se 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_invalid_status_transitioninvalid_request_error422El estado destino no es alcanzable desde el actual. El ciclo de vida es dirigido: draft pasa a scheduled o sent, sent a paid, overdue o annulled, y paid, cancelled y annulled son terminales.
invoice_not_cancellable_in_current_stateinvalid_request_error422Cancelar 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_stateinvalid_request_error422Una 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_stateinvalid_request_error422Solo 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_stateinvalid_request_error422Solo 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_actioninvalid_request_error422La 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_foundnot_found_error404El identificador no resuelve a ninguna factura de la empresa autenticada. Las facturas de otra empresa responden exactamente igual.
invoice_not_modifiable_in_current_stateinvalid_request_error422El campo que intentas cambiar está congelado para el estado actual — por ejemplo el régimen fiscal de una factura anulada.
invoice_not_paidinvalid_request_error422Se pidió un justificante de pago de una factura sin cobro registrado, así que no hay nada que certificar.
invoice_not_reschedulable_in_current_stateinvalid_request_error422Reprogramar 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_stateinvalid_request_error422Solo 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_stateinvalid_request_error422Desprogramar devuelve la factura de scheduled a draft, así que solo aplica mientras sigue esperando a emitirse.
invoice_not_unsendable_in_current_stateinvalid_request_error422Deshacer la marca de entrega solo aplica a una factura sent: limpia sent_at y mantiene la factura emitida.
invoice_requires_at_least_one_lineinvalid_request_error422La 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_numberinvalid_request_error422Ese número de factura existe en más de un ejercicio, así que por sí solo no identifica una única factura.
line_total_checksum_mismatchinvalid_request_error422El 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_invalidinvalid_request_error422El 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_periodinvalid_request_error422La operación trimestral no encontró facturas en el período pedido, así que no hay nada que empaquetar ni enviar.
payment_method_invalidinvalid_request_error422La misma allowlist cerrada que invalid_payment_method, reportada cuando el valor se rechaza al leer el campo de método de pago del payload.
reminder_not_applicableinvalid_request_error422El 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_pastinvalid_request_error422scheduled_for no es estrictamente futuro, así que no hay ninguna espera que reservar.
simplified_invoice_cannot_be_substitutedinvalid_request_error422Una 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_allowedinvalid_request_error422La 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_exceededinvalid_request_error422Las líneas llevarían la factura simplificada (F2) por encima del tope legal absoluto de 3.000 € IVA incluido.
suplido_line_cannot_carry_taxesinvalid_request_error422La 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_invoiceinvalid_request_error422La 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_referenceinvalid_request_error422La 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.

Notificaciones

CodeTypeHTTPDescripción
notification_not_foundnot_found_error404El identificador no corresponde a ninguna notificación de la empresa autenticada, o la notificación quedó fuera de la ventana de retención.

Pagos

CodeTypeHTTPDescripción
invalid_payment_dateinvalid_request_error422La fecha de pago queda fuera de la ventana admitida: no puede ser anterior a la fecha de emisión de la factura ni situarse en el futuro.
payout_reconciliation_amount_mismatchinvalid_request_error422El importe confirmado no coincide con el neto de la liquidación, así que la conciliación cerraría con una diferencia que nadie justifica.
receipt_not_availableinvalid_request_error422No hay justificante que emitir porque el documento no tiene ningún cobro registrado detrás.
stripe_payout_already_reconciledinvalid_request_error422La liquidación ya estaba conciliada, y la conciliación es terminal: repetirla contabilizaría dos veces el apunte bancario.
stripe_payout_not_foundnot_found_error404El identificador no resuelve a ninguna liquidación de la empresa autenticada.

Productos

CodeTypeHTTPDescripción
pack_in_useinvalid_request_error422El pack está referenciado por documentos emitidos, así que borrarlo rompería su composición.
pack_not_foundnot_found_error404El identificador no resuelve a ningún pack de la empresa autenticada.
pack_share_link_failedapi_error500No se pudo generar el enlace para compartir el pack. El pack en sí no queda afectado.
product_in_useinvalid_request_error422El producto está referenciado por documentos emitidos o por otras entradas del catálogo, y eliminarlo dejaría esas referencias colgando.
product_not_foundnot_found_error404El identificador no resuelve a ningún producto de la empresa autenticada.
sku_already_existsconflict_error409Otro producto de la empresa ya usa ese SKU, y el SKU identifica al artículo sin ambigüedad dentro del catálogo.

Facturas proforma

CodeTypeHTTPDescripción
invalid_expiry_dateinvalid_request_error422La fecha de vencimiento es anterior a la de emisión, o la supera en más de 365 días.
invalid_proforma_idinvalid_request_error400La referencia de proforma recibida no es un identificador válido, normalmente porque un valor interno sustituyó al id público.
invalid_proforma_numberinvalid_request_error422El número de proforma no sigue el formato canónico de numeración de su serie.
invalid_proforma_statusinvalid_request_error422El valor enviado como estado queda fuera del catálogo draft, accepted, rejected, expired, invoiced, cancelled.
invalid_proforma_uuidinvalid_request_error400El identificador de proforma de la ruta o del payload no es un UUID válido.
proforma_already_acceptedinvalid_request_error422El cliente ya aceptó la proforma, y la aceptación se registra una sola vez.
proforma_already_rejectedinvalid_request_error422La proforma ya está marcada como rechazada.
proforma_cannot_be_acceptedinvalid_request_error422La aceptación no procede desde el estado actual: una proforma facturada, cancelada o expirada ya no la admite.
proforma_cannot_be_rejectedinvalid_request_error422El rechazo no procede desde el estado actual: una vez facturada, cancelada o expirada, la proforma está cerrada.
proforma_cannot_be_sentinvalid_request_error422El envío por email no aplica a una proforma en estado terminal: no hay oferta viva que entregar.
proforma_invalid_status_transitioninvalid_request_error422El estado destino no es alcanzable desde el actual: un borrador se acepta, se cancela o expira; una proforma aceptada se factura, se rechaza o expira; facturada, cancelada y expirada son terminales.
proforma_not_convertible_in_current_stateinvalid_request_error422Convertir en factura exige que el cliente haya aceptado la proforma; desde cualquier otro estado no hay acuerdo que facturar.
proforma_not_deletable_in_current_stateinvalid_request_error422Solo se borra una proforma en borrador. Una vez aceptada, rechazada o facturada forma parte del rastro comercial.
proforma_not_draftinvalid_request_error422La operación solo tiene sentido mientras la proforma es un borrador, y esta ya ha avanzado.
proforma_not_editable_in_current_stateinvalid_request_error422Solo una proforma en borrador admite edición. Una vez aceptada, rechazada, expirada, facturada o cancelada, su contenido queda fijado.
proforma_not_foundnot_found_error404El identificador no resuelve a ninguna proforma de la empresa autenticada.
proforma_requires_at_least_one_lineinvalid_request_error422La proforma no lleva líneas, así que no hay importe que poner delante del cliente.
public_link_expires_at_exceeds_max_daysinvalid_request_error422La caducidad pedida para el enlace público supera la ventana máxima que permite tu plan para documentos compartidos.

Facturas de compra

CodeTypeHTTPDescripción
attachment_invalid_filenameinvalid_request_error422El nombre del fichero no es utilizable: está vacío, lleva componentes de ruta, o supera los 200 caracteres.
attachment_mime_not_allowedinvalid_request_error422El tipo de fichero queda fuera del conjunto admitido: PDF, PNG, JPEG, XML y HTML.
attachment_missingnot_found_error404La factura de compra existe pero no tiene fichero adjunto, así que no hay nada que descargar.
attachment_too_largeinvalid_request_error422El fichero supera el tamaño máximo permitido para un adjunto de documento.
cannot_attach_to_cancelled_purchase_invoiceinvalid_request_error422La factura está cancelada, y adjuntar documentos a un registro cancelado alteraría documentación ya cerrada.
invalid_purchase_invoice_idinvalid_request_error400La referencia de factura de compra recibida no es un identificador válido, normalmente porque un valor interno sustituyó al id público.
invalid_purchase_invoice_numberinvalid_request_error422El número de factura está vacío o no encaja con el formato admitido. En una factura de compra el número es el que imprimió el proveedor, no uno que genere Factuarea.
invalid_purchase_invoice_uuidinvalid_request_error400El identificador de factura de compra de la ruta o del payload no es un UUID válido.
operation_regime_invalidinvalid_request_error422El régimen de operación queda fuera del catálogo general, intracomunitaria, importacion_exportacion, isp.
purchase_invoice_already_existsconflict_error409Ese proveedor ya tiene registrada una factura de compra con el mismo número. El par proveedor + número identifica el documento sin ambigüedad y evita contabilizar dos veces el mismo gasto.
purchase_invoice_not_deletable_in_current_stateinvalid_request_error422Solo se borran las facturas de compra en borrador o canceladas. Una pendiente o pagada forma parte del libro de gastos.
purchase_invoice_not_draftinvalid_request_error422La operación solo aplica mientras la factura de compra es un borrador, y esta ya está registrada.
purchase_invoice_not_editable_in_current_stateinvalid_request_error422Solo se edita una factura de compra en borrador. Una vez registrada como pendiente, pagada o cancelada, su contenido respalda un apunte contable.
purchase_invoice_not_foundnot_found_error404El identificador no resuelve a ninguna factura de compra de la empresa autenticada.
purchase_invoice_requires_at_least_one_lineinvalid_request_error422La factura de compra no lleva líneas, así que no hay gasto ni IVA soportado que registrar.

Presupuestos

CodeTypeHTTPDescripción
quote_already_acceptedinvalid_request_error422El presupuesto ya estaba aprobado, y la aprobación se registra una sola vez.
quote_already_rejectedinvalid_request_error422El presupuesto ya está marcado como rechazado.
quote_expiredinvalid_request_error422El presupuesto pasó su fecha de validez, así que las condiciones ofrecidas ya no vinculan y no se puede aprobar ni convertir tal cual.
quote_not_foundnot_found_error404El identificador no resuelve a ningún presupuesto de la empresa autenticada.

Límite de tasa

CodeTypeHTTPDescripción
monthly_quota_exceededrate_limit_error429La empresa agotó la cuota mensual de llamadas que incluye su plan.
rate_limit_exceededrate_limit_error429La clave envió más peticiones de las que permite su ritmo en la ventana actual.

Facturas recurrentes

CodeTypeHTTPDescripción
invalid_frequency_intervalinvalid_request_error422El intervalo es menor que 1, así que la recurrencia nunca avanzaría a una siguiente ejecución.
invalid_frequency_typeinvalid_request_error422La frecuencia queda fuera del catálogo daily, weekly, biweekly, monthly, bimonthly, quarterly, semiannual, annual, custom.
invalid_holiday_handlinginvalid_request_error422La política de festivos queda fuera del catálogo skip, before, after, same.
invalid_recurring_invoice_idinvalid_request_error400La referencia de recurrencia recibida no es un identificador válido, normalmente porque un valor interno sustituyó al id público.
invalid_recurring_invoice_uuidinvalid_request_error400El identificador de recurrencia de la ruta o del payload no es un UUID válido.
recurring_already_activeinvalid_request_error422La recurrencia ya está en marcha, así que no hay nada que activar. Código legacy conservado por compatibilidad: los endpoints actuales reportan esto como recurring_invoice_already_active.
recurring_invoice_already_activeinvalid_request_error422La recurrencia ya está en marcha.
recurring_invoice_already_cancelledinvalid_request_error422La recurrencia ya estaba cancelada, y la cancelación es terminal.
recurring_invoice_already_pausedinvalid_request_error422La recurrencia ya está pausada, así que pausarla otra vez no cambia nada.
recurring_invoice_cancelled_cannot_resumeinvalid_request_error422Una recurrencia cancelada no se reanuda: la cancelación la cierra definitivamente, a diferencia de la pausa.
recurring_invoice_cannot_runinvalid_request_error422La recurrencia no puede generar una factura ahora mismo: no está en marcha, su ciclo terminó, o le faltan datos que la factura necesita. error.message indica el motivo concreto.
recurring_invoice_has_generated_invoicesinvalid_request_error422La recurrencia ya generó facturas, y esas facturas dependen de ella para su trazabilidad.
recurring_invoice_not_foundnot_found_error404El identificador no resuelve a ninguna recurrencia de la empresa autenticada.
recurring_invoice_requires_at_least_one_lineinvalid_request_error422La recurrencia no lleva líneas, así que cada factura generada saldría vacía.
recurring_not_activeinvalid_request_error422La operación necesita una recurrencia en marcha y esta está pausada, completada o cancelada. Código legacy conservado por compatibilidad con integraciones antiguas.

Request

CodeTypeHTTPDescripción
business_rule_violationinvalid_request_error422Una invariante del dominio rechazó la operación. Este código indica la familia; error.subcode nombra la regla concreta y error.message la explica.
conflicting_pagination_paramsinvalid_request_error422starting_after y ending_before viajaron en la misma petición. Recorren la colección en sentidos opuestos, así que solo puede aplicarse uno.
external_id_already_existsconflict_error409El external_id con el que concilias contra tu sistema ya está asignado a otro objeto del mismo tipo en esta empresa.
invalid_param_formatinvalid_request_error422Un form request legacy rechazó la forma de un valor. Los endpoints migrados reportan lo mismo como parameter_invalid_format o parameter_invalid_integer.
invalid_param_valueinvalid_request_error422Un form request legacy rechazó el valor de un campo. Los endpoints migrados reportan lo mismo como parameter_invalid_enum o parameter_invalid_range.
invalid_status_transitioninvalid_request_error422El estado solicitado no es alcanzable desde el estado en el que está ahora mismo el documento.
length_requiredinvalid_request_error411Llegó una petición con body en codificación chunked, sin declarar su tamaño. La API necesita conocer la longitud por adelantado para rechazar payloads excesivos antes de cargarlos en memoria.
metadata_too_many_keysinvalid_request_error422El objeto metadata supera el límite de 50 claves por recurso.
metadata_value_too_longinvalid_request_error422Un valor de metadata supera los 500 caracteres una vez serializado a texto.
method_not_allowedinvalid_request_error405La ruta existe pero no acepta el verbo HTTP utilizado.
missing_required_paraminvalid_request_error422Un form request legacy detectó que faltaba un campo obligatorio. Los endpoints ya migrados a los parsers canónicos reportan lo mismo como parameter_missing.
parameter_invalidinvalid_request_error422Un value object construido a partir del payload rechazó el valor recibido. error.subcode dice cuál: código de impuesto, código de país, tipo impositivo, etc.
parameter_invalid_booleaninvalid_request_error400Un parámetro que debe ser booleano recibió un valor fuera de las representaciones aceptadas (true/false, 1/0).
parameter_invalid_cursorinvalid_request_error400El cursor starting_after o ending_before no es un UUID válido, así que no puede apuntar a ninguna fila de la colección.
parameter_invalid_emptyinvalid_request_error400Un parámetro llegó con el valor vacío: un filtro in sin elementos, una comparación sin nada tras el operador, o un filtro de igualdad con la cadena vacía.
parameter_invalid_enuminvalid_request_error400El valor queda fuera del conjunto cerrado que acepta el parámetro. En los listados cubre además un operador de filtro distinto de eq, gte, lte, gt, lt, in o contains.
parameter_invalid_formatinvalid_request_error400El valor tiene el tipo correcto pero no la forma que exige el parámetro: una fecha, un patrón de identificador o una cabecera como Factuarea-Version.
parameter_invalid_integerinvalid_request_error400Un parámetro que debe ser un número entero recibió algo que no se puede interpretar como tal, por ejemplo limit=abc.
parameter_invalid_iso8601invalid_request_error400Un filtro de rango (gte, lte, gt, lt) recibió un valor que no es numérico ni una fecha ISO 8601.
parameter_invalid_rangeinvalid_request_error400Un parámetro numérico quedó fuera de sus límites. El caso habitual es limit, que debe estar entre 1 y 100.
parameter_invalid_stringinvalid_request_error400Un parámetro que debe ser texto recibió un array, un objeto o un valor que no se puede leer como cadena.
parameter_invalid_urlinvalid_request_error400Un campo que debe contener una URL absoluta recibió un valor que no lo es, normalmente por faltarle el esquema o el host.
parameter_invalid_uuidinvalid_request_error400Un campo de identificador recibió un valor que no es un UUID válido. Todo id de recurso en v1 es un UUID.
parameter_invalid_valueinvalid_request_error422El valor es sintácticamente correcto pero no admisible para este recurso: fuera del catálogo canónico del campo, o incoherente con el resto del payload.
parameter_missinginvalid_request_error400El endpoint exige un parámetro que la petición no llevaba. error.param dice cuál.
parameter_unknowninvalid_request_error400La petición lleva un parámetro que el endpoint no acepta: un filtro fuera de su allowlist, un campo de sort no ordenable, o el page de paginación por offset — v1 pagina por cursor.
payload_too_largeinvalid_request_error413El body de la petición supera el tamaño admitido: 1 MB con carácter general, 6 MB en los endpoints que aceptan ficheros.
profile_not_foundnot_found_error404La cabecera X-Active-Profile nombra una empresa que no existe o que no pertenece al árbol de gestoría de la clave autenticada. Ambos casos responden igual para que la API nunca revele empresas de otros tenants.
resource_already_existsconflict_error409Crear el objeto duplicaría uno que ya existe bajo una clave única — NIF, SKU, external id. error.details.existing_resource_id apunta al objeto que ya ocupa ese valor.
resource_conflictconflict_error409La operación chocó con el estado actual del recurso y no aplica ningún código de conflicto más específico.
resource_immutableinvalid_request_error422El objeto está cerrado a cambios para esta operación: su estado o su registro contable impiden modificarlo.
resource_lockedconflict_error409Otra operación retiene el recurso hasta terminar: las escrituras concurrentes sobre el mismo objeto se serializan en lugar de entrelazarse.
resource_not_deletableinvalid_request_error422El objeto existe, pero su estado o sus dependientes bloquean el borrado. En los borrados masivos este es el código por fila de cada entrada que no se pudo eliminar.
resource_not_foundnot_found_error404El identificador no resuelve a nada visible para la empresa autenticada. Los objetos de otra empresa responden exactamente igual, a propósito.
route_not_foundnot_found_error404La ruta no corresponde a ningún endpoint de v1. Suele ser una errata, un prefijo /v1 ausente o una ruta de otra área de la API.
unknown_filterinvalid_request_error422Un listado recibió un filtro que no conoce. Los parsers canónicos de v1 reportan esto como parameter_unknown; este código sobrevive para los endpoints aún sin migrar.
unsupported_api_versioninvalid_request_error400La cabecera Factuarea-Version está bien formada pero nombra una versión fuera del conjunto soportado.
unsupported_media_typeinvalid_request_error415Una petición con body declaró un Content-Type distinto de application/json.

Series

CodeTypeHTTPDescripción
cannot_archive_last_default_seriesinvalid_request_error422La serie es la única activa de su tipo de documento. Archivarla dejaría a la empresa sin numeración disponible y congelaría ese tipo de documento.
document_type_required_for_ambiguous_codeinvalid_request_error422Ese código de serie existe para más de un tipo de documento, así que por sí solo no identifica una única serie.
invalid_series_codeinvalid_request_error422El código de la serie está vacío, es demasiado largo, o lleva caracteres que no corresponden a un prefijo fiscal.
invalid_series_nameinvalid_request_error422El nombre de la serie está vacío o supera la longitud permitida.
invalid_series_numberinvalid_request_error422El número inicial no es válido: no es un entero positivo, o queda en el último número ya emitido o por debajo, lo que reemitiría números ya consumidos.
invalid_series_uuidinvalid_request_error400El identificador de serie de la ruta o del payload no es un UUID válido.
invalid_series_yearinvalid_request_error422El ejercicio no es un año de cuatro cifras válido para una serie de numeración.
monthly_requires_month_segmented_formatinvalid_request_error422El contador se reinicia cada mes pero la máscara de numeración no segrega por mes, así que dos meses arrancarían en el mismo correlativo y producirían números duplicados dentro del año.
series_already_archivedinvalid_request_error422La serie ya estaba archivada, y el archivado no se repite: una segunda llamada indica que el cliente ha perdido el estado real.
series_code_immutable_with_documentsinvalid_request_error422Cambiar el prefijo de una serie que ya emitió documentos reescribiría retroactivamente su identificador fiscal, mientras los clientes y la AEAT tienen el número original.
series_has_documentsinvalid_request_error422La serie ya numeró documentos, así que no se puede eliminar: la secuencia correlativa tiene que seguir siendo auditable.
series_immutableinvalid_request_error405Las series no son editables ni eliminables vía API: la continuidad legal de la numeración exige que su prefijo, su año y su contador se queden como están.
series_initial_number_creates_gapinvalid_request_error422El número inicial salta más allá del siguiente correlativo natural habiendo documentos del año en curso, y ese hueco en la secuencia no es admisible para la AEAT.
series_locked_by_verifactuinvalid_request_error422Al menos una factura de la serie tiene un registro de facturación aceptado por la AEAT, lo que congela el prefijo, el año y la base de numeración de la serie.
series_not_foundnot_found_error404El identificador no resuelve a ninguna serie de numeración de la empresa autenticada.
series_type_invalidinvalid_request_error422El tipo de documento de la serie queda fuera del catálogo invoice, quote, delivery_note, proforma, purchase_invoice, recurring_invoice.
series_year_lockedinvalid_request_error422La serie ya emitió documentos en su año vigente. Mover el año dejaría esos documentos apuntando a un ejercicio vacío mientras su base imponible está en otro.

Servidor

CodeTypeHTTPDescripción
dependency_unavailableservice_unavailable_error503Un servicio externo del que depende la operación no respondió a tiempo.
face_transmission_failedapi_error502La plataforma FACe —el punto de entrada de las administraciones públicas— estaba inaccesible o respondió con un fallo. El problema está aguas arriba, no en tu petición.
facturae_signing_failedapi_error500No se pudo producir la firma XAdES del fichero Facturae, normalmente porque el certificado de firma no es utilizable en ese momento.
internal_errorapi_error500Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.
maintenanceservice_unavailable_error503La plataforma está en ventana de mantenimiento y las escrituras se retienen a propósito.
pdf_generation_failedservice_unavailable_error503El servicio de renderizado no pudo producir el PDF. El documento y sus datos están intactos: lo que falló es el fichero.
register_sealing_failedapi_error500El sellado criptográfico del registro no se completó, así que el cierre quedó sin firmar en lugar de sellado con una firma rota.
send_failedapi_error500El documento no se entregó por email: el proveedor de correo rechazó el mensaje o estaba inaccesible.
service_unavailableservice_unavailable_error503El servicio, o una dependencia que necesita, no puede responder temporalmente.

Proveedores

CodeTypeHTTPDescripción
supplier_has_documentsinvalid_request_error422El proveedor está referenciado por facturas de compra registradas, y borrarlo dejaría esos gastos sin la parte que los emitió.
supplier_not_foundnot_found_error404El identificador no resuelve a ningún proveedor de la empresa autenticada.

Informes fiscales

CodeTypeHTTPDescripción
insufficient_data_for_reportinvalid_request_error422El período no tiene datos que declarar, o a una factura del período le falta un campo obligatorio para este modelo, típicamente el NIF del cliente.
invalid_periodinvalid_request_error422El período no identifica una declaración: el año queda fuera del rango admitido, o falta el trimestre o está fuera del rango 1 a 4 en un modelo trimestral.
report_format_invalidinvalid_request_error422El formato queda fuera del catálogo txt_aeat, pdf, excel.
tax_report_not_foundnot_found_error404El identificador no resuelve a ninguna declaración de la empresa autenticada.
tax_report_type_invalidinvalid_request_error422El tipo de declaración queda fuera del catálogo modelo_303, modelo_347, modelo_130.
unsupported_formatinvalid_request_error422El formato pedido no está disponible para este modelo: no toda declaración produce todas las salidas.

Impuestos

CodeTypeHTTPDescripción
custom_tax_creation_disabledauthorization_error403La creación de impuestos personalizados está deshabilitada para esta empresa.
duplicate_tax_default_for_document_typeinvalid_request_error422Ya hay otro impuesto del mismo tipo marcado como default para ese tipo de documento, y el par (tipo de impuesto, tipo de documento) admite un único default.
indirect_tax_regime_invalidinvalid_request_error422El régimen indirecto queda fuera del catálogo iva, igic, ipsi.
invalid_aeat_codeinvalid_request_error422El código de operación AEAT queda fuera del catálogo cerrado S1, S2, S3, E1-E6, N1, N2 que usan VeriFactu y el SII.
invalid_country_aeat_zoneinvalid_request_error422La zona territorial AEAT queda fuera del catálogo peninsula, canarias, ceuta, melilla.
invalid_country_codeinvalid_request_error422El código de país no tiene exactamente dos caracteres, así que no es un código ISO 3166-1 alfa-2 válido.
invalid_customer_visible_labelinvalid_request_error422La etiqueta que se muestra al cliente en el documento supera la longitud permitida.
invalid_descriptioninvalid_request_error422La descripción supera la longitud máxima permitida para el campo.
invalid_document_typeinvalid_request_error422El tipo de documento queda fuera del catálogo: invoice, quote, delivery_note, proforma, purchase_invoice, recurring_invoice.
invalid_rate_for_tax_regimeinvalid_request_error422El tipo no pertenece a la rejilla legal de su régimen: el IGIC admite 0, 3, 5, 7, 9,5, 15 y 20 %; el IPSI admite 0, 0,5, 1, 2, 4, 8 y 10 %.
invalid_tax_codeinvalid_request_error422El código del impuesto está vacío o supera los 50 caracteres.
invalid_tax_nameinvalid_request_error422El nombre del impuesto está vacío o supera los 255 caracteres.
invalid_tax_rateinvalid_request_error422El tipo impositivo queda fuera del rango permitido para su clase: IVA 0-27 %, retención 0-47 %, recargo de equivalencia 0-10 %, otros 0-100 %.
invalid_tax_type_filterinvalid_request_error422El filtro type del listado por tipo lleva un valor fuera del enum vat, retention, surcharge, other.
invalid_validity_windowinvalid_request_error422La ventana de vigencia está invertida: valid_until es anterior a valid_from.
system_tax_default_modification_forbiddenauthorization_error403Los defaults de los impuestos del catálogo compartido no se fijan sobre el impuesto: el catálogo es global y la preferencia es de tu empresa.
system_tax_immutableinvalid_request_error422El impuesto pertenece al catálogo canónico AEAT que trae el producto. Su tipo, su código y su nombre son fijos para que todas las empresas compartan la misma referencia fiscal.
system_tax_immutable_fieldinvalid_request_error422La actualización toca un campo congelado en un impuesto del sistema; error.param dice cuál.
system_tax_undeletableinvalid_request_error422Los impuestos del sistema forman parte del catálogo fiscal compartido y no se eliminan: borrarlos rompería los documentos que los referencian.
tax_applies_to_invalidinvalid_request_error422El ámbito del impuesto queda fuera del catálogo sale, purchase, both.
tax_code_already_existsconflict_error409Otro impuesto del catálogo ya usa ese código, y el código identifica al impuesto sin ambigüedad.
tax_id_requiredinvalid_request_error422La operación necesita el número de identificación fiscal (NIF, CIF o NIE) de la parte implicada y el registro no lo tiene.
tax_in_useinvalid_request_error422El impuesto está referenciado por documentos, productos o proveedores. Eliminarlo dejaría documentos históricos sin su referencia fiscal.
tax_inactive_cannot_be_defaultinvalid_request_error422Un impuesto desactivado no puede quedar como default, ni global ni por tipo de documento: sería un default oculto que ningún formulario puede elegir.
tax_not_foundnot_found_error404El identificador no corresponde a ningún impuesto del catálogo accesible para esta empresa.
tax_type_invalidinvalid_request_error422El tipo de impuesto queda fuera del catálogo vat, retention, surcharge, other.

VeriFactu

CodeTypeHTTPDescripción
alta_record_not_foundnot_found_error404La factura no tiene registro de alta, así que la operación que depende de él no tiene sobre qué trabajar.
anulacion_record_already_existsconflict_error409La factura ya tiene un registro de anulación en la cadena, y la anulación se declara una sola vez.
certificate_expiredinvalid_request_error422El certificado está fuera de su ventana de validez: ha caducado, o todavía no es válido.
certificate_nif_mismatchinvalid_request_error422El NIF del titular del certificado no coincide con el de la empresa. Los registros AEAT se firman en nombre de la empresa, así que ambos deben ser el mismo.
certificate_not_foundnot_found_error404La empresa no tiene ningún certificado FNMT que corresponda al identificador, o no tiene ninguno subido.
certificate_too_largeinvalid_request_error422El fichero supera el límite de 100 KB, cuando un certificado FNMT real pesa unos pocos kilobytes.
clock_drift_exceededinvalid_request_error422El reloj del servidor se desvió del NTP por encima del margen permitido. La marca de tiempo de generación entra en la huella AEAT, así que un reloj desincronizado produciría registros que la AEAT rechaza.
declaracion_already_existsconflict_error409La empresa ya tiene presentada la declaración responsable del SIF de ese período.
declaracion_not_foundnot_found_error404La empresa no tiene presentada la declaración responsable del SIF del período solicitado.
event_already_processedinvalid_request_error422Ese evento del SIF ya está registrado en la cadena de eventos, y cada evento se procesa exactamente una vez.
invalid_certificate_formatinvalid_request_error422El fichero no es un contenedor PKCS#12: sus primeros bytes no corresponden a la estructura ASN.1 que exige el formato, diga lo que diga la extensión.
invalid_certificate_passwordinvalid_request_error422La contraseña no abre el fichero del certificado.
max_retries_exceededinvalid_request_error422El registro agotó el presupuesto de reintentos técnicos de reenvío del XML almacenado. Reintentar el mismo contenido volvería a fallar igual.
mode_switch_blocked_until_year_endinvalid_request_error422El modo VeriFactu se activó en este ejercicio y ya se emitió al menos un registro de facturación. Dar marcha atrás degradaría la integridad de una cadena ya declarada a la AEAT.
record_already_acceptedinvalid_request_error422La AEAT ya aceptó el registro. La aceptación es terminal y su contenido queda congelado como parte de la cadena de huellas.
record_immutableinvalid_request_error422El registro pertenece a un ledger de solo-adición: una vez escrito, su contenido fiscal queda cerrado a modificaciones y a borrado.
record_not_rejectedinvalid_request_error422La subsanación solo aplica a registros que la AEAT rechazó por datos. Este registro está en otro estado — un fallo técnico, por ejemplo, lo cubre el reintento automático.
record_not_subsanableinvalid_request_error422El registro no se puede subsanar: no es un registro de alta, o no tiene factura de origen desde la que regenerar su contenido.
requires_annulmentinvalid_request_error422El contenido regenerado cambia un campo que entra en la huella —NIF del emisor, serie y número, fecha de expedición, tipo de factura, cuota o importe total— y la cadena no se puede reescribir.
sii_excludedinvalid_request_error422La empresa está registrada en el SII, y los obligados al SII quedan excluidos del reglamento VeriFactu.
verifactu_already_submittedinvalid_request_error422La factura ya tiene su registro de alta. Existe exactamente un alta por factura, así que una segunda rompería la idempotencia de la cadena.
verifactu_mode_invalidinvalid_request_error422El modo queda fuera del catálogo verifactu / no_verifactu.
verifactu_not_eligibleinvalid_request_error422La factura no se puede registrar ahora mismo en la AEAT: la empresa no está en modo VeriFactu, no tiene certificado activo, o el certificado está revocado o emitido para otro NIF.
verifactu_record_not_foundnot_found_error404El identificador no corresponde a ningún registro de facturación de la empresa autenticada.
verifactu_transmission_failedinvalid_request_error422El envío del registro a la AEAT no llegó a completarse: el endpoint estaba inaccesible o respondió con una incidencia.

Webhooks

CodeTypeHTTPDescripción
addon_requiredpayment_required_error402Crear endpoints de webhook pertenece al add-on Developer API, y la empresa no lo tiene activo: el nivel gratuito permite cero endpoints.
api_version_invalid_formatinvalid_request_error422La versión de payload del endpoint no es una fecha YYYY-MM-DD.
api_version_unsupportedinvalid_request_error422La versión de payload está bien formada pero no está entre las que sirve la plataforma.
custom_header_blocklistedinvalid_request_error422Una de las cabeceras personalizadas está reservada: la gestiona la capa HTTP (host, content-type, content-length, user-agent), la envía Factuarea como parte del contrato firmado (factuarea-*), o pertenece al proxy (x-forwarded-*).
custom_header_value_too_longinvalid_request_error422El valor de una cabecera personalizada supera los 1024 caracteres.
replay_delivery_not_retryableinvalid_request_error422Solo se reenvían las entregas fallidas. Una entrega que llegó bien, o una todavía en curso, no tiene nada que reenviar.
replay_event_expiredinvalid_request_error422El evento que respalda la entrega fue purgado por la política de retención de 30 días, así que ya no queda payload que reenviar.
timeout_seconds_out_of_rangeinvalid_request_error422timeout_seconds queda fuera del rango de 1 a 30 segundos.
too_many_custom_headersinvalid_request_error422El endpoint declara más de 20 cabeceras personalizadas.
webhook_delivery_not_foundnot_found_error404El identificador no corresponde a ningún intento de entrega, o la entrega queda fuera de la ventana de retención del histórico.
webhook_endpoint_degradedinvalid_request_error422El endpoint está degradado tras fallos repetidos de entrega, así que los pings de prueba se rechazan mientras siga en ese estado.
webhook_endpoint_not_foundnot_found_error404El identificador no resuelve a ningún endpoint de webhook de la empresa autenticada.
webhook_secret_recently_rotatedrate_limit_error429El secreto de firma se rotó hace menos de cinco minutos. La ventana de gracia permite que tu receptor acepte ambos secretos durante el cambio; rotar otra vez dentro de ella invalidaría firmas todavía en vuelo.

Códigos de error por categoría

Códigos de error de Facturas

En esta página

CuentaAutenticaciónAutorizaciónClientesEmpresasAlbaranesEmpleadosEventsIdempotencyFacturasNotificacionesPagosProductosFacturas proformaFacturas de compraPresupuestosLímite de tasaFacturas recurrentesRequestSeriesServidorProveedoresInformes fiscalesImpuestosVeriFactuWebhooks