Factuarea APIDevelopers
Soporte
Ir a la app

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.
sender_identity_not_verifiedinvalid_request_error422La empresa emisora todavía no ha acreditado su identidad, y sin eso no puede escribir a destinatarios externos desde el dominio remitente compartido. No es un cupo agotado ni un problema de permisos: la credencial tiene el scope, y esperar no lo resuelve.

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.
portfolio_max_api_keys_exceededauthorization_error422La cartera ya tiene el máximo de credenciales ACTIVAS. El tope se cuenta sobre la empresa gestora y sus hijas activas juntas, no por empresa, así que dar de alta otra hija para acuñarle su credencial tampoco deja crear ésta.
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.

Automatizaciones

CodeTypeHTTPDescripción
automation_action_order_invalidinvalid_request_error422La posición de un paso dentro de la secuencia no es un número entero, o es negativa. Esa posición es la que fija el orden en que se ejecutan las acciones.
automation_action_parameter_missinginvalid_request_error422No ha llegado un parámetro que la acción declara obligatorio. Se rechaza aquí, en vez de rellenarlo con un valor por defecto dentro del adaptador, para que el ensayo prediga la ejecución real.
automation_action_parameter_unknowninvalid_request_error422Una clave de parámetro no pertenece al esquema de la acción. Aceptarla guardaría una configuración que ningún adaptador lee, y la creerías activa hasta que la regla se disparase e hiciera otra cosa.
automation_action_parameter_value_invalidinvalid_request_error422Un parámetro de la acción lleva un valor fuera del conjunto que admite su esquema.
automation_action_parameters_invalidinvalid_request_error422Los parámetros de una acción no se sostienen como conjunto: un valor no es serializable, una clave no es texto, han llegado juntos dos parámetros excluyentes, o una pareja que exige uno de los dos ha llegado sin ninguno.
automation_action_type_invalidinvalid_request_error422Uno de los pasos declara un tipo de acción sin adaptador detrás, así que en esa posición no se ejecutaría nada.
automation_chain_depth_exceededinvalid_request_error422Una automatización disparó a otra hasta agotar el margen de encadenamiento, así que la ejecución se detiene antes de encolar ningún paso. Esperar no lo arregla: el mismo evento volvería a recorrer la misma cadena.
automation_condition_combinator_invalidinvalid_request_error422Una rama de la condición declara un combinador lógico fuera del conjunto admitido, así que la rama no se puede leer como un «y» ni como un «o».
automation_condition_depth_exceededinvalid_request_error422La condición anida más niveles de los que recorre el evaluador, así que la regla no se puede evaluar entera.
automation_condition_expression_invalidinvalid_request_error422La forma del árbol de condiciones no se sostiene: un nodo mal formado, un operador que recibe un valor de la clase equivocada, una ruta de campo que no es un camino con puntos, o un árbol que pasa del límite de profundidad o de nodos.
automation_condition_field_not_evaluableinvalid_request_error422La condición lee un campo que el disparador no publica como evaluable. La lista de campos admitidos nunca resuelve una ruta desconocida con un valor por defecto, porque un campo resuelto en silencio es justo el agujero que el sandbox existe para cerrar.
automation_condition_operator_invalidinvalid_request_error422Una comparación de la condición nombra un operador fuera del conjunto admitido.
automation_condition_operator_not_applicableinvalid_request_error422El operador no aplica al tipo del campo que compara: preguntar si un texto es mayor que otro no es una comparación que el evaluador pueda hacer.
automation_condition_operator_unsupportedinvalid_request_error422El evaluador no implementa ese operador, así que se detiene en vez de responder «falso»: un «falso» en silencio haría indistinguible «la condición no se cumple» de «no se puede evaluar».
automation_condition_payload_field_missinginvalid_request_error422La clave que lee la condición no viene en el payload del evento, que no es lo mismo que venir presente con valor nulo. Algunos eventos llevan un payload reducido: un borrado, por ejemplo, puede conservar solo el identificador.
automation_condition_payload_type_mismatchinvalid_request_error422El valor del evento contradice el tipo que el disparador declara para ese campo, y el evaluador no convierte tipos: una comparación por conversión daría un veredicto correcto por accidente y ocultaría que el payload cambió de forma.
automation_dry_run_event_type_mismatchinvalid_request_error422El ensayo se ha pedido con un tipo de evento distinto del disparador de la automatización que se ensaya, y una regla solo recibe eventos de su propio disparador. La predicción describiría una entrega que nunca va a ocurrir.
automation_event_company_unresolvableinvalid_request_error422El evento llegó al motor sin una empresa resoluble, y el motor se detiene en vez de suponer una: escribir una ejecución bajo una empresa sustituida rompería el aislamiento entre empresas.
automation_event_payload_not_resolvableinvalid_request_error422No se ha podido recuperar el contenido del evento, así que no hay payload que congelar en la ejecución. Ocurre cuando el recurso que hay detrás del evento ya no se puede leer en el momento de la entrega.
automation_monthly_budget_exhaustedpayment_required_error402La empresa agotó las ejecuciones de automatización que su plan incluye para el periodo en curso, así que la ejecución se detiene antes de encolar ningún paso. A diferencia de un límite de ritmo, esperar unos segundos no cambia nada: lo agotado es el presupuesto del ciclo.
automation_portfolio_scope_forbids_actioninvalid_request_error422Una de las acciones de la automatización actúa sobre datos de una sola empresa, y en alcance de cartera cada ejecución tiene por sujeto a una empresa gestionada distinta. Sólo se admiten las acciones que avisan a la gestoría o que no tocan ningún documento.
automation_portfolio_scope_not_availableauthorization_error403La empresa no puede crear automatizaciones sobre su cartera: o no tiene contratado el módulo de gestoría, o ella misma es una empresa gestionada por otra, y la relación es de un solo nivel.
automation_rate_limit_exceededrate_limit_error429La empresa superó las ejecuciones de automatización que su plan admite dentro de la ventana del limitador. El trabajo sí es admisible; sencillamente llegó demasiado rápido.
automation_replay_not_allowedinvalid_request_error422La ejecución existe y es tuya, pero relanzarla no procede: aún no ha terminado, terminó bien y su efecto ya se produjo, su desenlace volvería a tomar exactamente la misma rama, o no consta el motivo por el que acabó.
automation_rule_actions_emptyinvalid_request_error422La automatización no declara ninguna acción, así que no habría nada que ejecutar cuando saltara su disparador.
automation_rule_actions_limit_exceededinvalid_request_error422La regla contiene más de 50 acciones. Un solo evento disparador se multiplicaría en demasiados pasos, jobs en cola y posibles efectos externos.
automation_rule_already_deletedinvalid_request_error422La automatización ya estaba dada de baja. El borrado es lógico y no devuelve éxito en silencio la segunda vez, para que dos bajas distintas no se confundan entre sí.
automation_rule_company_mismatchinvalid_request_error422La automatización que iba a materializarse no pertenece a la empresa del evento, así que la ejecución no se crea: congelar el snapshot de un evento —cliente, importes, identificador fiscal— en filas de otra empresa no se permite nunca.
automation_rule_name_invalidinvalid_request_error422El nombre está vacío o supera el límite de longitud. El nombre es lo que identifica la automatización en los listados y en el histórico de sus ejecuciones.
automation_rule_not_foundnot_found_error404No existe ninguna automatización con ese identificador para la empresa autenticada. Una regla de otra empresa responde exactamente igual, así que la respuesta nunca revela si existe en otro sitio.
automation_rule_scope_immutableinvalid_request_error422La petición intenta cambiar el alcance de una automatización que ya existe. El alcance se fija al crearla porque determina de qué empresas observa los eventos, y cambiarlo reinterpretaría todas sus ejecuciones anteriores.
automation_rule_scope_invalidinvalid_request_error422El alcance enviado no pertenece al catálogo de la automatización. Sólo existen dos: la empresa que la crea y la cartera de empresas gestionadas.
automation_rule_status_transition_invalidinvalid_request_error422La automatización no puede pasar de su estado actual al que pides: activar, pausar y dar de baja aceptan cada uno sus propios estados de origen.
automation_rule_uuid_invalidinvalid_request_error422El identificador no es un UUID v7 válido. Las automatizaciones direccionan sus recursos por el id que devuelve la API, nunca por un número interno.
automation_rule_version_not_foundnot_found_error404La automatización existe, pero no tiene ninguna versión con ese número: cada guardado publica una versión nueva y la numeración nunca reutiliza un valor.
automation_rule_version_number_invalidinvalid_request_error422El número de versión es menor que 1. Las versiones se numeran desde uno hacia arriba, en el orden en que se publicaron.
automation_rule_version_snapshot_not_foundnot_found_error404La ejecución apunta a una versión de la automatización cuya definición congelada no está guardada, así que no hay definición que ejecutar: una ejecución corre siempre la versión con la que empezó, nunca la regla viva.
automation_run_not_foundnot_found_error404No existe ninguna ejecución de automatización con ese identificador para la empresa autenticada. Una ejecución de otra empresa responde exactamente igual, así que la respuesta nunca revela si existe en otro sitio.
automation_run_status_transition_invalidinvalid_request_error422La ejecución no puede pasar de su estado actual al solicitado: el ciclo de vida de una ejecución solo admite las transiciones que declara su estado.
automation_run_step_not_foundnot_found_error404La ejecución existe y es tuya, pero no tiene ningún paso en ese índice. Una ejecución materializa todos sus pasos al arrancar y el número no cambia después.
automation_run_uuid_invalidinvalid_request_error422El identificador de la ejecución no es un UUID v7 válido.
automation_step_index_invalidinvalid_request_error422El índice de un paso no puede ser negativo: ninguna ejecución direcciona un paso así.
automation_step_status_transition_invalidinvalid_request_error422El paso no puede pasar de su estado actual al solicitado. Es lo que impide reclamar dos veces un paso ya terminado, y esa guarda es la que hace que un relanzamiento produzca cada efecto una sola vez.
automation_step_subject_company_mismatchinvalid_request_error422El elemento sobre el que iba a actuar la acción no pertenece a la empresa de la ejecución, o no se ha podido determinar a qué empresa pertenece. En los dos casos el paso aborta antes de invocar el adaptador, así que no se produce ningún efecto.
automation_subject_company_ownership_not_verifiedinvalid_request_error422Al preparar la ejecución no se pudo demostrar que la empresa del evento siga siendo una empresa gestionada y activa de quien creó la automatización. Puede que el vínculo se archivara, que la empresa se diera de baja o que la ejecución llegara con datos cruzados.
automation_trigger_not_foundnot_found_error404El disparador no está en el catálogo que tu empresa puede ver. Un nombre que no existe y un disparador real cuyo módulo tu empresa no tiene concedido responden igual, así que la respuesta nunca confirma cuál de los dos casos es.
automation_trigger_payload_contract_unknowninvalid_request_error422El disparador no publica contrato de campos evaluables, así que no hay catálogo contra el que resolver una condición.
automation_trigger_type_invalidinvalid_request_error422La escritura lleva un disparador que no está en el catálogo disponible para tu empresa, así que la regla no recibiría ningún evento.

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.

Contactos

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.
bank_account_usage_requiredinvalid_request_error422La cuenta bancaria no declara para qué sirve: ni collection ni payment, y tampoco marca un uso predeterminado del que deducirlo. Una cuenta sin propósito no puede usarse en cobros ni en pagos.
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.
contact_not_foundnot_found_error404El identificador no resuelve a ningún contacto comercial de la empresa autenticada.
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.
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.
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.

Albaranes

CodeTypeHTTPDescripción
delivery_note_cannot_be_sentinvalid_request_error422El albarán ya está facturado o cancelado: entregarlo ahora le daría al cliente un documento superado.
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.

Exportaciones

CodeTypeHTTPDescripción
export_budget_exceededrate_limit_error429Se ha agotado el presupuesto horario de TRABAJO DE EMPAQUETADO de la empresa. No es un límite de peticiones: cuenta documentos empaquetados y artefactos generados contra el disco y el pool de render que comparten todos los inquilinos, así que ni repartir las llamadas ni usar otra credencial cambian nada. El subcode dice cuál de los dos ejes se agotó: export_documents_budget (el contenido empaquetado) o export_artifacts_budget (el número de ficheros generados).
export_byte_cap_exceededinvalid_request_error413La descarga empaquetada supera el tope de BYTES de ese tipo de artefacto. No cuenta documentos sino peso, así que un lote pequeño de documentos muy pesados —con plantilla ilustrada o adjuntos— también lo alcanza. El subcode dice en qué momento se rechazó: before_writing, cuando el peso estimado ya lo superaba y NO se llegó a escribir nada, o while_writing, cuando el peso real lo superó durante el empaquetado y el fichero parcial se descartó.
export_document_cap_exceededinvalid_request_error413La descarga empaquetada pide MÁS DOCUMENTOS de los que admite ese tipo de artefacto. No es un límite de peticiones ni un problema de permisos: es el tamaño de lo que se pide en una sola llamada, y el mismo tope rige en la aplicación web y en la API, de modo que partir el trabajo entre superficies no lo esquiva.

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_requiredinvalid_request_error422La petición llegó sin cabecera Idempotency-Key y esta operación entrega un efecto que no se puede deshacer —un correo enviado, un fichero generado, un cargo—, así que su ventana de transición ya cerró para el entorno de esta credencial.
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.

Integraciones

CodeTypeHTTPDescripción
shopify_api_version_expiredapi_error500La versión de la API de administración con la que hablamos con la tienda ya no está soportada. Shopify no devuelve un error cuando eso pasa: sirve la versión estable más antigua con código 200, así que la avería aparece como campos que dejan de estar en la respuesta.
shopify_credentials_rejectedinvalid_request_error422La tienda ha contestado y ha rechazado el token de acceso, o no había ninguno que usar. En Shopify el token nace de la autorización de la app y el comerciante puede revocarla desde su panel en cualquier momento, así que un token que funcionaba ayer puede no valer hoy sin que nadie haya tocado la configuración.
shopify_store_unreachableapi_error502La tienda no ha contestado: se agotó el tiempo de espera, falló el transporte, Shopify devolvió un error propio o se agotó el presupuesto de coste de consulta de la API de administración. Lo que falla está aguas arriba y no en la credencial.
store_already_connectedinvalid_request_error422Esa tienda ya está conectada a tu empresa con el mismo proveedor. El par proveedor + tienda remota es único por empresa, así que conectarla dos veces dejaría dos tiendas ingiriendo los mismos pedidos y facturándolos por duplicado.
store_external_id_mismatchinvalid_request_error422El identificador remoto que envías no corresponde a ninguna tienda que tu empresa haya autorizado para esa integración. En los proveedores que firman sus avisos con el secreto de la aplicación —Shopify—, ese identificador decide a qué empresa se factura cada venta, así que sólo se admite el de una tienda que haya pasado por la autorización.
store_not_foundnot_found_error404El identificador no corresponde a ninguna tienda conectada de la empresa autenticada. Una tienda de otra empresa responde exactamente igual, de modo que la respuesta nunca revela si existe en otro sitio.
store_url_not_allowedinvalid_request_error422La dirección base de la tienda no es un destino de salida autorizado para tu empresa. Releer pedidos desde la tienda abriría una conexión hacia un host que nadie ha aprobado.
woocommerce_credentials_rejectedinvalid_request_error422La tienda ha contestado y ha rechazado la credencial, o la credencial no podía usarse: falta la clave, falta el secreto o la dirección base no es https. La autenticación viaja en la cabecera sobre HTTPS, así que una tienda publicada en texto claro entregaría las dos piezas en el primer salto y por eso se rechaza antes de salir.
woocommerce_rest_route_missinginvalid_request_error422La tienda ha contestado, pero su API REST no está publicada: WordPress ha devuelto que la ruta no existe. Lo habitual es que los enlaces permanentes estén en modo simple, de modo que /wp-json/ no se sirve. La credencial puede ser perfectamente correcta.
woocommerce_store_unreachableapi_error502La tienda no ha contestado: se agotó el tiempo de espera, falló el transporte o su alojamiento devolvió un error propio. Lo que falla está aguas arriba, en la instalación del comerciante, y no en la plataforma ni en la credencial.

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 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_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_cannot_be_sentinvalid_request_error422La 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_transitioninvalid_request_error422El 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_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 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_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.
rectified_invoice_inanulableinvalid_request_error422Esta 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_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.

MCP

CodeTypeHTTPDescripción
mcp_guardrail_violationinvalid_request_error422La llamada infringe una regla fiscal declarada y se ha rechazado LOCALMENTE, antes de ejecutar nada: no se ha creado, modificado ni borrado ningún documento. Es el único código del catálogo que ninguna ruta de la API v1 puede emitir — quien lo recibe está hablando por MCP. El subcode dice cuál de los nueve guardrails se ha infringido, y los datos del error traen guardrail_uri (el resource que explica la regla) y rule_id (la regla concreta, con la forma BR-XXX-NNN).

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.
payment_already_reversedinvalid_request_error422El cobro ya está anulado, y su rastro no se pisa con una segunda anulación: el motivo, el instante y el autor del primero son el registro contable de por qué la factura dejó de estar cobrada.
payment_reversal_invalidinvalid_request_error422La nota de la anulación supera los 500 caracteres admitidos.
payment_reversal_reason_invalidinvalid_request_error422El motivo de la anulación no pertenece al catálogo cerrado: solo se admiten devolución de adeudo SEPA, disputa o retrocesión de tarjeta, error de imputación, efecto impagado y error de registro.
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.

Tarifas

CodeTypeHTTPDescripción
duplicate_price_list_nameinvalid_request_error422Otra tarifa de la empresa ya usa ese nombre, que debe ser único dentro del tenant.
inactive_price_listinvalid_request_error422La tarifa está inactiva y solo puede consultarse para explicar documentos históricos, no seleccionarse para una operación nueva.
invalid_price_list_iteminvalid_request_error422La entrada de tarifa tiene un destino, importe o unidad incompatible, o duplica el mismo producto, variante y presentación dentro de la tarifa.
price_list_in_useinvalid_request_error422La tarifa está asignada a clientes o borradores y eliminarla dejaría esas referencias sin origen de precio.
price_list_not_foundnot_found_error404El identificador no resuelve a ninguna tarifa 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_cannot_be_sentinvalid_request_error422El presupuesto está rechazado, convertido, caducado o cancelado: ya no es una oferta viva que entregar.
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
account_probation_limit_exceededrate_limit_error429La empresa está dentro de su PERIODO DE CONFIANZA de cuenta nueva, y el techo que ha rechazado esta llamada lo pone la EDAD DE LA CUENTA, no su plan. Una cuenta recién creada arranca con un margen reducido que se ensancha solo según madura.
company_monthly_quota_exceededrate_limit_error429La empresa agotó el volumen mensual que su plan concede al conjunto de sus claves.
company_rate_limit_exceededrate_limit_error429La empresa superó el ritmo por minuto que su plan concede al conjunto de sus claves, no el de una clave suelta.
email_delivery_circuit_openrate_limit_error429El envío de correo está CORTADO temporalmente, por una incidencia del proveedor o por un problema de entrega de esta empresa. No es un cupo: es un corte de seguridad para no seguir quemando reputación de envío mientras la entrega falla.
email_recipient_budget_exceededrate_limit_error429Se ha agotado el presupuesto de DESTINATARIOS DISTINTOS de la empresa en la ventana. No es un límite de peticiones: cuenta buzones alcanzados, así que ni repartir el envío en más llamadas ni usar otra credencial cambian nada.
monthly_quota_exceededrate_limit_error429La empresa agotó la cuota mensual de llamadas que incluye su plan.
pdf_generation_budget_exceededrate_limit_error429Se ha agotado el presupuesto horario de TRABAJO DE RENDER de PDF. No es un límite de peticiones: cuenta renders contra el pool de Chrome que comparten todos los inquilinos, así que ni repartir las llamadas ni usar otra credencial cambian nada. El subcode dice cuál de los dos cupos se agotó: company_budget (el de la empresa entera) o document_budget (el de este documento suelto, mientras los demás siguen generando).
portfolio_monthly_quota_exceededrate_limit_error429La cuota MENSUAL de la cartera se ha agotado. Se cuenta sobre la empresa gestora y sus hijas activas en conjunto, así que el consumo de una hija agota el de todas.
portfolio_rate_limit_exceededrate_limit_error429El techo por minuto que se ha alcanzado es el de la CARTERA —la empresa gestora y todas sus hijas activas sumadas—, no el de esta credencial ni el de esta empresa. Por eso ni repartir el tráfico entre credenciales ni dar de alta otra empresa hija cambian nada: las dos siguen contando en el mismo cubo.
rate_limit_exceededrate_limit_error429La clave envió más peticiones de las que permite su ritmo en la ventana actual.
upload_in_flight_budget_exceededrate_limit_error429La empresa tiene demasiados bytes atravesando a la vez el disco temporal (importaciones tabulares y sus previsualizaciones, UBL, OCR y restauración de copia). Es un presupuesto de bytes EN VUELO, no de espacio ocupado: no consume cubo de peticiones ni aparece en las cabeceras de límite.

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.

Almacenamiento

CodeTypeHTTPDescripción
storage_quota_exceededpayment_required_error402El fichero no cabe en el espacio que le queda a la empresa. El saldo que se compara es el AGREGADO de todas las superficies que guardan bytes —vault, PDF de contratos, marca de empresa, parcelas, packs, adjuntos de compra, certificados, extractos bancarios y firmas de albarán—, así que el disco puede estar lleno por una superficie que no es la que estás usando.

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.
invalid_url_targetinvalid_request_error422El host de destino no es una dirección públicamente alcanzable, así que no entregamos ahí: se rechazan los rangos privados (RFC 1918), loopback, link-local, CGNAT (100.64.0.0/10), ULA IPv6 (fc00::/7) y multicast. Pese a lo que dice el mensaje, la restricción aplica en todos los entornos, no solo en producción.
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.
Anterior

Catálogo de errores

Todos los códigos de error de la API pública agrupados por categoría, con una página por código donde se explica su causa y qué hacer.

Siguiente

Gestión de errores

Envoltorio de error normalizado, catálogo de type y code con anclas estables, y estrategia de reintentos.

En esta página

CuentaAutenticaciónAutorizaciónAutomatizacionesEmpresasContactosAlbaranesEmpleadosEventsExportacionesIdempotencyIntegracionesFacturasMCPNotificacionesPagosTarifasProductosFacturas proformaFacturas de compraPresupuestosLímite de tasaFacturas recurrentesRequestSeriesServidorAlmacenamientoInformes fiscalesImpuestosVeriFactuWebhooks
¿Te echamos una mano?Contactar con soporte