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
access_level_raise_forbiddeninvalid_request_error422Se intentó subir el nivel de acceso sobre una cuenta gestionada cuyo titular ya la reclamó. Desde la reclamación solo el titular puede subir ese nivel; el proveedor solo puede bajarlo.
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.
administrator_key_not_grantableinvalid_request_error422Una de las secciones de grants es una llave del Administrador (gestión de usuarios, plan y suscripción, API y desarrolladores o certificado digital) y esas secciones no se conceden a un miembro.
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.
enterprise_contract_transition_requiredinvalid_request_error422La cuenta gestionada tiene un contrato enterprise y, al terminar la gestión, su pago pasaría al titular sin que Factuarea haya fijado todavía el plan con el que continúa. Nunca se crea una suscripción sin precio, así que no se ha cambiado nada.
external_advisor_already_assignedinvalid_request_error422La cuenta ya tiene un asesor externo marcado: solo puede haber uno por cuenta.
grant_company_not_in_accountinvalid_request_error422El NIF del grant no es un NIF real de la cuenta o queda fuera del ámbito de NIF de la credencial. La respuesta es la misma en los dos casos, sin revelar cuál.
grants_only_for_memberinvalid_request_error422Solo un miembro con rol member puede tener permisos por NIF (grants). El titular (owner) y los administradores (admin) alcanzan todos los NIF de la cuenta, así que un grant sobre ellos no significaría nada.
import_file_invalidinvalid_request_error422Uno de los ficheros de la importación no se puede leer con el formato de la plantilla: no es un CSV legible, su cabecera no aparece en las 20 primeras líneas, le falta una columna obligatoria o tiene una línea rota. param indica qué fichero falla (accounts_file o customers_file) y el mensaje, la columna o la línea. No se ha escrito nada.
import_file_too_largeinvalid_request_error413Uno de los ficheros de la importación supera los 5 MB. El tamaño se comprueba antes de leer ninguna fila, así que no se ha procesado ni escrito nada. param indica qué fichero falla (accounts_file o customers_file).
import_in_progressconflict_error409Ya hay una importación masiva de esta cuenta proveedora en curso. Las importaciones de una misma cuenta se aplican de una en una para no crear cuentas, cargos ni NIF por duplicado, así que esta no se ha aplicado ni ha escrito nada.
import_row_limit_exceededinvalid_request_error422Uno de los ficheros de la importación trae más filas de las que admite una importación: 100 en el fichero de cuentas (accounts_file) y 1.000 en el de clientes (customers_file). Las filas se cuentan antes de leerlas, así que no se ha procesado ni escrito nada. param indica qué fichero falla.
invitation_expiredinvalid_request_error422La invitación existe y es de esta empresa, pero su ventana de aceptación ya se cerró, así que quien la recibió no puede canjearla.
invitation_not_foundnot_found_error404El identificador no corresponde a ninguna invitación pendiente de la empresa autenticada: puede haberse cancelado, haberse aceptado ya o pertenecer a otra empresa.
live_credential_requiredauthorization_error403Una clave de pruebas intentó modificar una cuenta de producción. Solo ocurre en las operaciones que cambian la cuenta —miembros, invitaciones, titularidad, traspasos de NIF, cartera de NIF, claves y asientos—: una clave de pruebas no puede alterar datos reales.
managed_account_external_ref_in_other_environmentconflict_error409La referencia externa ya la usa una cuenta gestionada del otro entorno (real o de pruebas). La referencia es única entre los dos entornos, y la respuesta no nombra esa cuenta porque este entorno no la lista. No se ha escrito nada.
managed_account_not_claimableinvalid_request_error422La cuenta gestionada es de pruebas, y una cuenta de pruebas nunca se reclama: no tiene vale de reclamación que emitir ni que reemitir.
managed_account_plan_not_self_serveinvalid_request_error422Se pidió el plan enterprise para una cuenta gestionada. Una cuenta gestionada se crea o se cambia en emprendedor o empresario; enterprise solo lo asigna Factuarea por contrato.
managed_account_provider_in_trialinvalid_request_error422La cuenta proveedora está en periodo de prueba y pidió una cuenta gestionada real, que se cobra. Durante la prueba solo se pueden crear cuentas gestionadas de pruebas.
managed_accounts_limit_reachedinvalid_request_error422La cuenta proveedora ya tiene tantas cuentas gestionadas reales con la gestión vigente como admite su tope. Las cuentas gestionadas de pruebas no cuentan para ese tope.
member_is_last_ownerinvalid_request_error422La operación dejaría el NIF sin ninguna persona que lo administre: el miembro que se da de baja, o que se degrada a un rol sin administración, es el último con rol owner o admin en ese NIF.
member_not_foundnot_found_error404El identificador no corresponde a ningún miembro del equipo de la cuenta: o esa persona nunca perteneció a la empresa autenticada, o es de otra. La superficie de cuenta responde igual en ambos casos.
module_not_grantableinvalid_request_error422Una de las secciones de grants no se puede conceder: no es una sección exclusiva de administradores (un miembro ya accede a ella con permisos normales) o la empresa no la tiene por su plan.
nif_transfer_expiredinvalid_request_error422El traspaso de NIF se emitió de verdad, pero su plazo de validez venció. A diferencia de un traspaso no reconocido, esta respuesta solo le llega a quien ya tenía uno real, así que no revela nada nuevo.
nif_transfer_invalidinvalid_request_error422El traspaso de NIF presentado no autoriza nada: su secreto está mal copiado, truncado, ya consumido o nunca se emitió. Todos esos casos responden igual a propósito, para que la operación no sirva para sondear qué traspasos existen.
owner_transfer_forbiddenauthorization_error403Quien hace la petición no está autorizado a transferir la titularidad de la cuenta: o no es el titular actual, o el destinatario propuesto no puede recibirla. Es cuestión de permiso, no de payload mal formado.
permissions_not_applicable_to_administratorinvalid_request_error422El miembro es owner o admin de la cuenta: tiene todos los permisos de su plan y no admite restricciones ni concesiones de secciones.
permissions_not_applicable_to_employeeinvalid_request_error422La persona es un empleado del portal del empleado: su acceso lo gobierna el portal y no la matriz de secciones, así que no admite restricciones ni concesiones.
plan_limit_exceededpayment_required_error402Se alcanzó un límite de recursos del plan de la empresa.
privileged_scope_requiredauthorization_error403La operación exige el privilegio de proveedor de cuentas (accounts:read o accounts:write) y no se cumple: o la cuenta de la clave no lo tiene concedido, o la persona que emitió la clave ya no es propietaria ni administradora de la cuenta. Las dos causas responden igual.
provisioning_account_claimedconflict_error409El titular ya reclamó esta cuenta gestionada y la administra por su cuenta: ya no se puede reclamar otra vez, reemitir su vale de reclamación ni volver a provisionarla con la misma referencia externa.
relation_already_existsinvalid_request_error422Ya hay un acceso pendiente o vigente entre estas dos cuentas, y solo puede haber uno abierto por cada pareja de cuentas.
relation_company_not_in_grantorinvalid_request_error422La lista de NIF del acceso no es válida: o nombra un NIF que no pertenece a la cuenta que cede el acceso, o viene vacía. El error señala el campo company_ids y no dice cuál de los NIF falla.
relation_invitation_expiredinvalid_request_error422La invitación de acceso existe y sigue pendiente, pero su plazo de aceptación venció, así que ya no se puede aceptar.
relation_invitation_invalidinvalid_request_error422La invitación de acceso presentada no sirve: su secreto no existe, ya se usó, se revocó o va dirigida a otra cuenta. Todos esos casos responden igual a propósito, para que la operación no sirva para sondear invitaciones ajenas.
relation_self_grant_not_allowedinvalid_request_error422La cuenta indicada no puede recibir el acceso: o es la misma cuenta que lo cede, o el identificador no corresponde a una cuenta válida. Los dos casos responden igual.
relation_transition_not_allowedinvalid_request_error422El acceso entre cuentas está en un estado que no admite el cambio pedido: por ejemplo, aceptar uno que ya está vigente o reenviar la invitación de uno que ya terminó.
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.
company_read_onlyauthorization_error403Quien emitió la credencial tiene acceso de solo lectura (nivel view) a la empresa efectiva: su rol en la cuenta le permite ver ese NIF, no escribir en él. El nivel efectivo es el menor entre el guardado en la credencial y el que la persona tiene hoy.
emitter_capability_restrictedauthorization_error403La persona que emitió la credencial tiene retirada, en la empresa efectiva, la sección o la acción que exige la operación. Es la misma restricción por módulo que el administrador de la empresa le puso en la aplicación web, y se aplica aunque su nivel de acceso al NIF sea operate.
feature_not_available_in_planauthorization_error403La funcionalidad no está incluida en el plan de la empresa.
forbidden_actionauthorization_error403La acción se rechaza aunque el scope sea el correcto. Los motivos habituales son: tu credencial llega al NIF por una relación entre cuentas (acceso cedido a tu cuenta, o cuenta gestionada) y la operación pertenece a la cuenta dueña del NIF —el registro de peticiones, los eventos, los webhook endpoints, la facturación de la cuenta, el uso de automatizaciones y las escrituras de credenciales de cobro conectadas nunca están disponibles por una relación—; el NIF es de una cuenta gestionada cuyo titular ya la paga, así que su proveedor puede consultarlo y editar sus datos pero ya no activarlo, desactivarlo ni archivarlo; la persona que emitió la credencial no es owner ni admin de la cuenta, o la credencial no alcanza todos los NIF de la cuenta; o 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 cuenta ya tiene el máximo de credenciales ACTIVAS que admite una cartera. El tope rige cuando la cuenta tiene dos o más NIF reales y se cuenta sobre todas las credenciales activas de la cuenta, no por NIF, así que dar de alta otro NIF 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_active_rules_limit_exceededpayment_required_error402La empresa ya tiene activas todas las automatizaciones que permite su plan.
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 un NIF distinto de la cartera. Sólo se admiten las acciones que avisan a la titular de la cuenta o que no tocan ninguna entidad.
automation_portfolio_scope_not_availableauthorization_error403La empresa no puede crear automatizaciones sobre su cartera: o no tiene concedido el módulo de gestoría, o no es la titular de su cuenta. La cartera la representa la titular, así que un NIF adicional de la cuenta nunca tiene cartera propia.
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 su cuenta (sus otros NIF y los que otra cuenta le cede con nivel de operación).
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 en la cartera de la cuenta de quien creó la automatización, alcanzable con nivel de operación y activa. Puede que el NIF se archivara, se desactivara o se traspasara a otra cuenta, que la relación que lo cedía se revocara, terminara o bajara a solo consulta, 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.

Facturación

CodeTypeHTTPDescripción
customer_offer_benefit_invalidinvalid_request_error422Las condiciones de la oferta no son válidas. Revisa los campos indicados.
customer_offer_billing_state_conflictconflict_error409El estado de facturación ha cambiado o necesita revisión. Consulta la operación antes de continuar.
customer_offer_catalog_unavailableservice_unavailable_error503El catálogo de cobro no está configurado o no puede verificarse; no es una restricción del plan del cliente.
customer_offer_collection_not_restorableinvalid_request_error422La compra no puede cobrarse o restaurar su saldo de forma segura. No se deja deuda para otra factura.
customer_offer_combination_invalidinvalid_request_error422Los días extra sólo se combinan con un descuento o precio de plan permanente.
customer_offer_discount_conflictconflict_error409Esta compra ya tiene una oferta o un descuento vigente para el mismo concepto. No se acumulan automáticamente.
customer_offer_forbiddenauthorization_error403La operación no cumple las condiciones o permisos vigentes.
customer_offer_gateway_unavailableservice_unavailable_error503El proveedor de pagos no está disponible. Comprueba esta operación antes de reintentar.
customer_offer_idempotency_conflictidempotency_error409Este intento ya corresponde a otras condiciones. Conserva la operación y comprueba su estado.
customer_offer_invalid_termsinvalid_request_error422Las condiciones de la oferta no son válidas. Revisa los campos indicados.
customer_offer_legacy_outcome_unknownconflict_error409Una operación anterior de facturación sigue pendiente de comprobación.
customer_offer_negotiated_price_invalidinvalid_request_error422Revisa el precio neto, producto, intervalo y número de ciclos acordados.
customer_offer_not_eligibleinvalid_request_error422Esta oferta no es compatible con la empresa, producto o estado actual.
customer_offer_operation_in_progressconflict_error409Ya hay una operación en curso para este concepto. Comprueba su estado antes de continuar.
customer_offer_payment_method_requiredpayment_required_error402Esta compra necesita un método de pago. Añádelo y actualiza las condiciones antes de confirmar.
customer_offer_phase_incompatibleconflict_error409La suscripción tiene un cambio programado incompatible. No se ha sustituido.
customer_offer_price_mapping_conflictconflict_error409El estado de facturación ha cambiado o necesita revisión. Consulta la operación antes de continuar.
customer_offer_purchase_failedpayment_required_error402El pago ha fallado y se ha verificado que esta compra no se ha aplicado. Consulta la operación antes de volver a intentarlo.
customer_offer_quote_changedconflict_error409Las condiciones han cambiado. Actualiza la cotización antes de confirmar.
customer_offer_quote_expiredconflict_error409La cotización ha vencido. Actualízala y revisa las condiciones.
customer_offer_quote_unavailableservice_unavailable_error503No se puede verificar el importe. La confirmación queda bloqueada.
customer_offer_state_conflictconflict_error409El estado de facturación ha cambiado o necesita revisión. Consulta la operación antes de continuar.
customer_offer_trial_baseline_changedconflict_error409La prueba ha cambiado. Actualiza la cotización para ver la fecha vigente.
customer_offer_trial_limit_exceededinvalid_request_error422La ampliación superaría el máximo de 180 días de prueba.
customer_offer_trial_not_eligibleinvalid_request_error422Sólo puedes ampliar una prueba activa del plan acordado. Una prueba vencida no se reinicia.
customer_offer_unavailableinvalid_request_error422La oferta no está disponible, ha vencido o ha agotado sus canjes.

Empresas

CodeTypeHTTPDescripción
additional_nif_charge_failedpayment_required_error402El cobro inmediato del NIF adicional fue rechazado: la tarjeta se denegó, necesita autenticación, o el proveedor de pago estaba inaccesible. Si no se cobra, el NIF no se añade ni se activa y no queda ningún cargo.
additional_nif_not_in_planauthorization_error403La cuenta tiene un plan vigente, pero ese plan no incluye NIF adicionales: solo Empresario y Enterprise (también en prueba) los admiten. No se ha cobrado nada ni se ha escrito ningún cambio.
additional_nif_plan_requiredpayment_required_error402La cuenta no tiene un plan vigente, así que no hay suscripción sobre la que cobrar el NIF adicional. No se ha cobrado nada ni se ha escrito ningún cambio.
billing_managed_by_providerauthorization_error403La facturación de esta cuenta la paga otra cuenta, así que esta no puede contratar por su cuenta un NIF adicional. No se ha cobrado nada ni se ha escrito ningún cambio.
company_inactiveauthorization_error403La empresa que nombra el segmento {company} de la ruta está dentro del ámbito de la credencial, pero está desactivada y no se puede operar hasta que vuelva a estar activa.
payment_method_requiredpayment_required_error402Añadir o activar un NIF adicional cobra su cuota de inmediato, y la cuenta opera en modo real sin método de pago configurado. No se ha cobrado nada ni se ha escrito ningún cambio.

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.
import_not_foundinvalid_request_error404La importación de contactos o su reporte no está disponible en la empresa autenticada.
mapping_header_not_foundinvalid_request_error422Una columna del mapeo de la importación no existe en las cabeceras del fichero subido.
supplier_has_documentsinvalid_request_error422El proveedor está referenciado por gastos registrados, y borrarlo dejaría esos gastos sin su emisor.
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_batch_billing_state_conflictconflict_error409La facturación necesita revisión antes de continuar con esta operación.
employee_batch_forbiddenauthorization_error403Ya no tienes permiso para esta operación. Comprueba el estado antes de empezar otra.
employee_batch_idempotency_conflictidempotency_error409Esta solicitud corresponde a otros datos. Revisa la operación antes de preparar un lote nuevo.
employee_batch_quote_changedconflict_error409Las condiciones han cambiado. Actualiza la cotización y acepta el nuevo importe.
employee_batch_quote_expiredconflict_error409La cotización ha vencido. Actualízala y revisa el importe.
employee_batch_quote_unavailableservice_unavailable_error503No se puede obtener un importe fiable. Inténtalo de nuevo sin iniciar otro pago.
employee_batch_state_conflictconflict_error409Esta acción ya no está disponible. Consulta el estado actual de la operación.
employee_inactiveinvalid_request_error422El empleado está dado de baja: es de solo lectura y no admite operaciones nuevas, como fichar la entrada, asignarle un horario o una política de ausencias, aprobarle una ausencia que pasa de su fecha de baja o invitarle al portal. No se ha escrito nada.
employee_not_foundnot_found_error404El empleado no existe o no es accesible en esta empresa.
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_mutation_outcome_unknownconflict_error409Una operación anterior de empleados sigue pendiente de comprobación. No repitas el cargo.
employee_seat_operation_in_progressconflict_error409Hay una operación de plazas en curso. Recupérala antes de iniciar otra.
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.
employee_seat_phase_incompatibleconflict_error409La suscripción tiene condiciones programadas que no pueden conservarse mediante esta modificación de plazas.
employee_seats_not_in_planauthorization_error403El plan de la cuenta no incluye el control horario (el módulo control_horario, por plan o por una concesión manual), así que no se pueden comprar plazas de empleado. No se ha cobrado nada ni se ha escrito ningún cambio; bajar o mantener las plazas contratadas sigue permitido.
invalid_hire_dateinvalid_request_error422La fecha de alta del empleado quedaría después de su fecha de baja: al corregir hire_date con una fecha posterior a la baja ya registrada, o al dar de baja con una termination_date anterior al alta. El empleado no se modifica.

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.

Empresas gestionadas

CodeTypeHTTPDescripción
gestoria_seat_preview_unavailableservice_unavailable_error503No se pudo verificar el importe del cargo de empresas gestionadas; no es una operación gratuita por contrato.

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_error422Esa 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. Un external_id ya emitido que se reenvía con otro tipo o total en POST /v1/companies/{company}/invoices no devuelve este error, sino el 409 unattended_replay_mismatch.

Integraciones

CodeTypeHTTPDescripción
charge_rule_invalidinvalid_request_error422La regla no es coherente: la condición, el resultado, el motivo de no facturación, el concepto o el IVA no encajan entre sí o no son válidos. El campo conflictivo se indica en param.
charge_rule_limit_reachedinvalid_request_error422La cuenta de Stripe ya tiene el número máximo de reglas de tratamiento de cobros.
charge_rule_not_foundnot_found_error404La regla de tratamiento de cobros no existe en la cuenta de Stripe indicada o no pertenece a tu empresa.
connect_return_domain_already_existsconflict_error409El host que intentas dar de alta ya es uno de los dominios de retorno de tu cuenta. Se compara normalizado (minúsculas, sin puerto ni ruta), así que App.Ejemplo.com y app.ejemplo.com son el mismo dominio.
connect_return_domain_limit_reachedinvalid_request_error422Tu cuenta ya tiene el número máximo de dominios de retorno que admite, y no se ha guardado el nuevo. El tope es por cuenta y cuenta todos los dominios dados de alta.
connect_return_domain_not_foundnot_found_error404El dominio de retorno que indicas en la ruta no existe en tu cuenta, o pertenece a otra: las dos respuestas son idénticas a propósito para no revelar los dominios de otras cuentas.
connect_return_url_not_allowedinvalid_request_error422El host de la return_url no figura entre los dominios de retorno de la cuenta de la clave con la que inicias la conexión de Stripe. Solo se aceptan direcciones https cuyo host (exacto, sin comodines) esté dado de alta en esa cuenta, para que nadie pueda llevar a la persona a un sitio que no controlas.
invalid_connection_methodinvalid_request_error422El método de conexión indicado no existe para este proveedor.
platform_account_subscriptions_owned_by_billinginvalid_request_error422La cuenta de Stripe conectada es la de la propia plataforma: las cuotas de suscripción de Factuarea las factura Facturación directamente, así que esa cuenta no admite la autofacturación de suscripciones (subscription_autoinvoicing_enabled).
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.
stripe_account_linked_elsewhereconflict_error409Esa cuenta de Stripe ya está vinculada y activa en otra empresa de Factuarea. Una cuenta de Stripe activa solo puede pertenecer a una empresa.
stripe_oauth_exchange_failedinvalid_request_error422Stripe no ha confirmado la autorización de la cuenta: el código de autorización ha caducado, ya se usó o fue denegado.
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
amount_reconciliation_failedinvalid_request_error422Los importes con IVA incluido no se pueden repartir en líneas que sumen exactamente lo cobrado, así que no se ha emitido nada antes que alterar el total. Lo causa, por ejemplo, una retención o un recargo de equivalencia que mueven el total más que una diferencia de redondeo.
corrective_client_change_requires_substitutioninvalid_request_error422La rectificativa va a nombre de un cliente distinto del de la factura original (p. ej. por un error en los datos del cliente): solo puede ser una sustitución, porque por diferencias el importe quedaría a nombre de quien no recibió la factura.
corrective_full_cancellation_with_linesinvalid_request_error422Anular la factura entera por diferencias (correction_type total, full en la API, con correction_nature: I) no admite líneas: la rectificativa copia en negativo todas las de la original.
corrective_invoice_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.
corrective_substitution_negative_amountinvalid_request_error422En una rectificativa por sustitución (correction_nature: S, o full con lines sin naturaleza) cada línea lleva el importe FINAL de la factura correcta, así que ninguna cantidad puede ser negativa (art. 15.5 RD 1619/2012; VERI*FACTU no admite base negativa en una sustitución). El precio unitario nunca es negativo: el signo va en la cantidad.
corrective_substitution_requires_fullinvalid_request_error422Una rectificativa por sustitución (correction_nature: S) sustituye la factura entera; no hay sustitución parcial.
exemption_cause_contradicts_taxed_linesinvalid_request_error422La factura lleva una causa de exención de cabecera que declara la operación sin IVA (exención, no sujeción o inversión del sujeto pasivo) y alguna línea de operación tiene un IVA mayor que cero.
export_limit_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.
face_submission_attempt_conflictconflict_error409Otra petición modificó el intento de envío a FACe (reserva o conciliación) mientras actuabas sobre él.
face_submission_completion_failedapi_error500FACe respondió al envío pero la plataforma no pudo guardar el resultado localmente.
face_submission_rejectedinvalid_request_error422FACe analizó el envío y lo rechazó con su propio código de error (por ejemplo un código DIR3 erróneo, una firma no válida o un duplicado). A diferencia de una transmisión incierta, FACe no registró la factura.
face_transmission_uncertainconflict_error409La factura se envió a FACe pero se desconoce el resultado, así que FACe puede haberla registrado o no.
facturae_artifact_unavailableapi_error500El archivo Facturae conservado para ese envío no se puede leer del almacenamiento porque falta o está dañado. El fallo es nuestro.
facturae_operation_forbiddenauthorization_error403El actor no puede realizar esa operación de Facturae; details.reason indica si se trata de los permisos del actor, de la autoridad del emisor, del acceso a la factura o del derecho a enviarla.
invalid_correction_natureinvalid_request_error422correction_nature solo acepta I (por diferencias: la rectificativa lleva el importe de la rectificación, con su signo) o S (sustitución: lleva la factura tal y como queda, con las líneas finales).
invalid_correction_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_delivery_channelinvalid_request_error422El canal de envío queda fuera del catálogo, que solo tiene dos valores: email (se registra solo cuando el servidor de correo acepta el mensaje) y manual (un envío que hiciste por tus propios medios).
invalid_facturae_structured_datainvalid_request_error422Los datos estructurados necesarios para construir el archivo Facturae no son válidos: un valor es incorrecto, los totales no cuadran con las líneas o el XML generado no cumple el esquema.
invalid_invoice_business_datainvalid_request_error422Los datos comerciales de la factura (referencias de línea, centros administrativos o sus roles) contienen un valor no válido.
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 de numeración de su serie (por defecto SERIE-AAAA-NNN; las rectificativas llevan el número correlativo de su propia serie, p. ej. R-2026-001).
invalid_invoice_payment_termsinvalid_request_error422El calendario de pago de la factura incumple una regla, por ejemplo plazos que no suman el total, fechas no válidas o falta la cuenta bancaria contractual.
invalid_invoice_statusinvalid_request_error422El valor enviado como estado de factura queda fuera del catálogo del ciclo de vida documental (draft, scheduled, issued, overdue, cancelled, annulled). Antes de la versión de API 2026-10-01 issued se publica como sent, y allí donde la API lee un estado de entrada (los filtros de estado, el cambio de estado masivo) sent se toma como issued. paid es un valor válido para leer y para filtrar, pero no para escribir: registra un cobro en su lugar.
invalid_invoice_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_administrative_precondition_requiredinvalid_request_error428El cambio del routing administrativo no indicó sobre qué versión se basa.
invoice_administrative_version_conflictconflict_error409El routing administrativo de la factura (sus centros administrativos) cambió después de leerla.
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_rectified_in_fullinvalid_request_error422La factura ya está anulada por completo (una rectificativa total por diferencias), y entonces no admite ninguna rectificativa más; o está sustituida por completo, y entonces no admite otra rectificación total.
invoice_already_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_marked_as_sentinvalid_request_error422La marca de envío registra que una factura emitida llegó al cliente, así que solo aplica a facturas issued u overdue. Un borrador o una factura programada todavía no son la factura fiscal, y una cancelada o anulada ya no lo es.
invoice_cannot_be_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_due_date_not_last_instalmentinvalid_request_error422La factura tiene plazos de pago y su vencimiento (due_on) falta o no es la fecha del último plazo, que es cuando vence la factura.
invoice_invalid_status_transitioninvalid_request_error422El estado destino no es alcanzable desde el actual. El ciclo de vida documental es dirigido: draft pasa a scheduled, issued o cancelled, scheduled vuelve a draft o avanza a issued, issued pasa a overdue o annulled, overdue a annulled, y cancelled y annulled son terminales. El ciclo es el mismo en todas las versiones de API; antes de 2026-10-01 el estado issued se publica como sent. Estar cobrada no es un paso de ese ciclo: se lee del ledger de cobros.
invoice_not_cancellable_in_current_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, esté cobrada o no: issued u overdue (una factura emitida se publica como sent antes de la versión de API 2026-10-01). Un borrador, una factura programada, una cancelada o una anulada no tienen nada que rectificar.
invoice_not_deletable_in_current_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 envío solo aplica a una factura emitida (issued u overdue; publicada como sent antes de la versión de API 2026-10-01) sin cobros vigentes: limpia sent_at y sent_via y conserva su estado fiscal.
invoice_payment_terms_precondition_requiredinvalid_request_error428El cambio del calendario de pago no indicó sobre qué versión se basa.
invoice_payment_terms_version_conflictconflict_error409El calendario de pago de la factura cambió después de leerla.
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_type_change_not_allowedinvalid_request_error422Solo un borrador alterna entre factura completa (F1) y simplificada (F2). Una rectificativa, una sustitutiva (F3) o una rectificativa de simplificada (R5) conservan su tipo, y una simplificada sin cliente no pasa a completa sin indicar antes el destinatario.
invoice_without_retained_presentationinvalid_request_error422Una factura del trimestre no tiene presentación documental retenida (es anterior a la captura o nunca se inicializó), así que no puede incluirse en el paquete trimestral. Aparece como error_code en los failures del manifiesto del ZIP trimestral, donde la factura queda fuera, y como subcódigo de una violación de regla de negocio en el correo trimestral.
invoice_year_required_for_ambiguous_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.
operation_date_after_issue_dateinvalid_request_error422operation_on es posterior a issued_on. Una fecha de operación posterior a la de expedición solo es válida en pagos anticipados (clave de régimen 14 o 15).
pack_return_invalidinvalid_request_error422La devolución de un componente de pack en una factura rectificativa incumple las reglas de devolución. El pack no está en la factura que se rectifica, el producto no es uno de sus componentes, la cantidad no es negativa, el precio difiere del precio repartido original o se devuelven más unidades de las vendidas.
payment_method_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 issued ni overdue (una factura emitida se publica como sent antes de la versión de API 2026-10-01), no hay email de destinatario, falta el enlace público o está desactivado, o ya salió otro recordatorio en las últimas 24 horas.
scheduled_for_in_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_invoices_disabledinvalid_request_error422La empresa no tiene habilitadas las facturas simplificadas, así que no se puede crear una factura de tipo F2.
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.
tax_rate_mismatchinvalid_request_error422La línea elige un impuesto por id (tax_rate_id, retention_rate_id o surcharge_rate_id) y lo contradice: declara un tax_rate, retention_rate o surcharge_rate distinto del de ese impuesto, o el impuesto es de otra clase que su campo (por ejemplo, una retención en surcharge_rate_id). El IVA elegido califica además la línea (régimen, calificación AEAT y causa de exención), así que los dos datos deben coincidir.
unattended_replay_mismatchidempotency_error409Ya se emitió una factura con ese external_id con otro tipo u otro total, así que la petición no puede tratarse como un reenvío de la misma venta. Se responde con 409, code y subcode unattended_replay_mismatch y param=external_id: el external_id identifica UNA operación y no caduca. No es idempotency_key_reused, el 422 de una Idempotency-Key reutilizada con otro payload.

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 no puede ser posterior a hoy. Una fecha anterior a la emisión sí se admite: se registra como cobro o pago anticipado.
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.
reversal_reason_reservedinvalid_request_error422El motivo issued_in_error está reservado a la anulación de una factura expedida por error; no sirve para revertir un cobro suelto.
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.

PDF

CodeTypeHTTPDescripción
invalid_pdf_artifact_fingerprintinvalid_request_error422La huella del artefacto PDF no es válida.
invalid_pdf_template_configurationinvalid_request_error422Un valor de la configuración de la plantilla incumple una regla del modelo de plantilla; param indica la ruta del campo afectado.
pdf_artifact_not_foundnot_found_error404El artefacto PDF no existe en esta empresa, o era una vista previa que ha caducado.
pdf_artifact_not_readyservice_unavailable_error503El PDF todavía se está preparando.
pdf_commercial_identity_not_foundnot_found_error404La identidad comercial no existe en esta empresa.
pdf_commercial_identity_requiredinvalid_request_error422El modo de marca de la plantilla (logotipo o imagen) necesita una identidad comercial y la empresa no tiene ninguna por defecto.
pdf_commercial_identity_unavailableinvalid_request_error422La identidad comercial existe pero está archivada o no es compatible con esta operación.
pdf_engine_profile_unavailableapi_error500El perfil de generación PDF no está disponible.
pdf_engine_unreachableservice_unavailable_error503El motor de generación PDF no ha respondido (caído, reiniciándose o en mitad de un despliegue). Es transitorio: la misma petición sale bien cuando el motor vuelve, y no se ha creado ni cambiado nada.
pdf_image_resource_unavailableapi_error500El recurso de imagen del PDF no está disponible.
pdf_legal_source_changedconflict_error409La fuente jurídica actual ya no coincide con la presentación retenida.
pdf_library_association_coverage_incompleteapi_error500La plataforma no pudo comprobar todos los valores por defecto, series o recurrencias que usan la plantilla, así que no se puede garantizar el impacto de la operación. El fallo es nuestro.
pdf_library_impact_conflictconflict_error409Los valores por defecto, series o recurrencias afectados por la operación cambiaron después de revisar su impacto.
pdf_main_template_requiredconflict_error409La empresa ya trabaja con la biblioteca de plantillas PDF, donde el diseño (pdf_template) y el color de acento (accent_color) de la personalización se aplican a su plantilla principal, y no tiene ninguna plantilla principal a la que aplicarlos.
pdf_original_corruptapi_error500No se puede verificar la integridad del PDF original.
pdf_original_layout_unavailableapi_error500El diseño con el que se generó el PDF original ya no está disponible en esta versión de Factuarea.
pdf_original_unavailableapi_error500El PDF original no está disponible.
pdf_payload_resource_unavailableapi_error500Los recursos necesarios para preparar el PDF no están disponibles.
pdf_presentation_conflictconflict_error409La presentación cambió después de leerla, así que el expected_version enviado está desfasado.
pdf_presentation_context_changedconflict_error409Los datos con los que se construyó la vista previa (documento, empresa o contexto de plantilla) cambiaron después de generarla.
pdf_presentation_etag_mismatchconflict_error412El ETag enviado en If-Match ya no coincide con la presentación guardada, que se modificó después de leerla.
pdf_presentation_invalidinvalid_request_error422La presentación no cumple una regla de contenido o de campo.
pdf_presentation_not_foundnot_found_error404La presentación documental no existe en esta empresa o no pertenece al documento consultado.
pdf_presentation_not_readyinvalid_request_error422La presentación revisionada aún no está disponible para esta empresa: su activación está pendiente.
pdf_presentation_precondition_requiredinvalid_request_error428El cambio de la presentación no indicó sobre qué versión se basa.
pdf_signature_personal_data_forgottennot_found_error410Los datos personales de la firma de esta presentación se han eliminado.
pdf_template_access_deniedauthorization_error403La credencial o el usuario no tiene permiso para realizar esta operación en la biblioteca de plantillas PDF.
pdf_template_archivedinvalid_request_error422La plantilla PDF está archivada y una plantilla archivada no se puede asignar ni editar.
pdf_template_asset_conflictconflict_error409Ya existe un activo de plantilla con ese identificador, por lo que la subida lo sobrescribiría.
pdf_template_asset_not_foundnot_found_error404El activo de la plantilla (logotipo, imagen o fuente) no existe en esta empresa o fue eliminado.
pdf_template_default_replacement_requiredinvalid_request_error422Archivar la plantilla dejaría valores por defecto o asociaciones sin plantilla y no se indicó ningún reemplazo.
pdf_template_not_foundnot_found_error404La plantilla PDF no existe en esta empresa.
pdf_template_precondition_failedconflict_error412El ETag enviado en If-Match ya no coincide con la plantilla guardada, que se modificó después de leerla.
pdf_template_precondition_requiredinvalid_request_error428Modificar la plantilla exige indicar la versión en la que se basa y no se envió ninguna.
pdf_template_version_conflictconflict_error409La plantilla se modificó después de leerla, así que el expected_version enviado está desfasado.
preparation_requiredconflict_error409Hay que preparar el PDF de esta presentación antes de solicitarlo.

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_item_not_foundnot_found_error404El artículo indicado no existe en la tarifa: ya se retiró o el identificador no es de esta tarifa.
price_list_not_foundnot_found_error404El identificador no resuelve a ninguna tarifa de la empresa autenticada.

Productos

CodeTypeHTTPDescripción
duplicate_pack_componentinvalid_request_error422El mismo producto, variante, presentación o configuración aparece más de una vez en el pack.
duplicate_promotion_iteminvalid_request_error422El mismo artículo aparece más de una vez en la oferta y cada artículo solo puede tener una regla de precio.
gross_weight_not_allowedinvalid_request_error422Este artículo no admite peso bruto de transporte: los servicios no pesan, los productos y variantes con unidad base de masa (KGM, GRM) ya pesan su cantidad, y una presentación de medida variable se pesa en cada línea.
invalid_gross_weightinvalid_request_error422El peso bruto de transporte no es un número, es cero o negativo, tiene más de 4 decimales o supera el techo de su columna. En una línea de mercancía de un documento de control, también cuando la cantidad por el peso por unidad da un peso de línea que redondea a 0 kg o supera ese techo.
invalid_pack_componentinvalid_request_error422Un componente no puede formar parte de un pack, por ejemplo un producto que se vende por peso real, cuyo importe solo se conoce en la báscula.
invalid_pack_imageinvalid_request_error422El archivo subido no es una imagen de pack utilizable: no es un JPG, PNG, WebP o GIF, supera el tamaño máximo o no se ha podido leer.
invalid_pack_pricinginvalid_request_error422El precio del pack no es válido para su modo: falta el valor, está fuera de rango, lleva más de dos decimales o el descuento iguala o supera el precio de los productos por separado.
invalid_pack_status_transitioninvalid_request_error422El cambio de estado pedido no está permitido desde el estado actual del pack, por ejemplo activar un pack sin canales de venta o restaurar uno con la composición bloqueada.
invalid_promotioninvalid_request_error422Un campo de la oferta incumple alguna de sus reglas: el nombre, el texto que ve la web, las fechas, la zona horaria, los canales o la lista de artículos.
invalid_promotion_iteminvalid_request_error422Un artículo de la oferta no es válido: su destino, su modo, su base o su valor incumple una regla.
pack_composition_too_smallinvalid_request_error422Un pack necesita al menos dos componentes, o un solo producto contado con cantidad de 2 o más.
pack_group_not_contiguousinvalid_request_error422Las líneas de un mismo pack no van seguidas en el documento. Hay otra línea entre ellas.
pack_image_limit_reachedinvalid_request_error422El pack ya tiene el máximo de 5 imágenes.
pack_in_useinvalid_request_error422El pack está referenciado por documentos emitidos, así que borrarlo rompería su composición.
pack_line_lockedinvalid_request_error422Una línea que pertenece a un grupo de pack no puede cambiar su producto, cantidad, precio unitario ni descuento.
pack_lines_must_be_expandedinvalid_request_error422Las líneas de un pack no se pueden construir a mano. El servidor reparte el precio entre los componentes del pack y fija él mismo los datos del grupo.
pack_not_foundnot_found_error404El identificador no resuelve a ningún pack de la empresa autenticada.
pack_not_sellableinvalid_request_error422El pack no se puede añadir a un documento: está archivado, inactivo, fuera de su vigencia o uno de sus componentes está inactivo.
pack_price_allocation_impossibleinvalid_request_error422El precio del pack no se puede repartir entre sus componentes porque no tienen precio por separado.
pack_price_unreachableinvalid_request_error422El precio con IVA pedido no se puede alcanzar exactamente porque el IVA se redondea línea a línea.
pack_print_mode_not_allowedinvalid_request_error422Solo existe el modo de impresión full_breakdown: cada producto del pack se imprime como una línea normal, con el nombre del pack.
pack_snapshot_invalidinvalid_request_error422La fotografía del pack enviada con la línea del documento no lleva firma, está alterada o está mal formada.
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.
promotion_not_foundnot_found_error404El identificador no corresponde a ninguna oferta de la empresa autenticada.
promotion_read_onlyinvalid_request_error422La oferta ya ha terminado o se ha cancelado, así que es de solo lectura y no admite más cambios.
promotion_startedinvalid_request_error422La oferta ya ha empezado y forma parte del historial de precios. Una oferta empezada solo admite cambiar su fin y no se puede borrar.
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.
slug_already_existsconflict_error409El slug ya lo usa, como actual o anterior, otro producto o pack de la empresa.

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.

Gastos

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_error404El gasto 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 gasto 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 gasto 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 los gastos en borrador o cancelados. Uno pendiente o pagado forma parte del libro de gastos.
purchase_invoice_not_draftinvalid_request_error422La operación solo aplica mientras el gasto es un borrador, y este ya está registrado.
purchase_invoice_not_editable_in_current_stateinvalid_request_error422Solo se edita un gasto en borrador. Una vez registrado como pendiente, pagado o cancelado, su contenido respalda un apunte contable.
purchase_invoice_not_foundnot_found_error404El identificador no resuelve a ningún gasto de la empresa autenticada.
purchase_invoice_requires_at_least_one_lineinvalid_request_error422El gasto no lleva líneas, así que no hay importe ni IVA soportado que registrar.

Escáner de gastos

CodeTypeHTTPDescripción
duplicate_override_reason_requiredinvalid_request_error422No se ha indicado un motivo válido para continuar pese al duplicado.
duplicate_resolution_requiredinvalid_request_error422Existe una posible duplicidad que requiere revisión.
invalid_inbound_signatureauthentication_error401No se ha podido autenticar la firma del correo entrante.
invalid_purchase_scan_transitioninvalid_request_error422El estado actual del escaneo no permite esta transición.
module_upgrade_requiredauthorization_error403El plan actual no incluye la capacidad solicitada de OCR.
ocr_company_daily_quota_exceededrate_limit_error429La empresa ha agotado su cuota diaria de OCR.
ocr_company_quota_exceededrate_limit_error429La empresa ha agotado su cuota mensual de OCR.
purchase_scan_already_convertedconflict_error409El escaneo ya está vinculado a un gasto.
purchase_scan_not_foundnot_found_error404El escaneo no existe o no pertenece a la empresa activa.
purchase_scan_retry_not_allowedinvalid_request_error422El escaneo no admite otro intento en su estado actual.
purchase_scan_review_incompleteinvalid_request_error422Faltan datos obligatorios o los importes revisados no cuadran.
purchase_scan_source_unavailableinvalid_request_error422El original del escaneo fue purgado o ya no está disponible en el almacenamiento seguro.
scan_batch_too_largeinvalid_request_error413El lote supera el tamaño total permitido.
scan_decompression_limit_exceededinvalid_request_error413El archivo supera el límite seguro al descomprimirse.
scan_file_too_largeinvalid_request_error413Un archivo supera el máximo de 20 MiB.
scan_page_limit_exceededinvalid_request_error413El documento supera el límite de páginas configurado.
scan_pixel_limit_exceededinvalid_request_error413La resolución del documento supera el límite de procesamiento seguro.
scan_storage_unavailableservice_unavailable_error503El almacenamiento seguro del original no está disponible.
scanner_admin_requiredauthorization_error403La acción requiere permisos de administración del escáner.
stale_scan_versionconflict_error409El escaneo ha cambiado desde la última lectura.
unsafe_scan_fileinvalid_request_error422El original no ha superado la inspección de seguridad.
unsupported_purchase_currencyinvalid_request_error422La divisa del documento no está admitida para la conversión.
unsupported_purchase_document_typeinvalid_request_error422El original es un albarán, pedido, presupuesto, proforma u otro documento que no acredita un gasto fiscal.
unsupported_scan_formatinvalid_request_error422El formato real del archivo no es compatible.
validation_failedinvalid_request_error422Los datos del escaneo no cumplen las restricciones indicadas.

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.
import_row_quota_exceededrate_limit_error429Las nuevas filas de importación superarían la cuota mensual de filas del plan.
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 cuenta entera —todos sus NIF en conjunto—, así que el consumo de un NIF agota el de todos.
portfolio_rate_limit_exceededrate_limit_error429El techo por minuto que se ha alcanzado es el de la CARTERA —una cuenta con dos o más NIF reales, donde se suman las peticiones de todas sus credenciales sobre cualquier NIF que alcancen—, no el de esta credencial ni el de esta empresa. Por eso ni repartir el tráfico entre credenciales ni dar de alta otro NIF en la cuenta cambian nada: todo sigue 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.
invalid_recurring_payment_terms_templateinvalid_request_error422La plantilla de calendario de pago de la recurrencia, que se aplica a cada factura que genera, no es válida.
invalid_recurring_presentation_policyinvalid_request_error422La política de presentación de la recurrencia, que define cómo se presentan las facturas que genera, tiene un valor no 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_completed_cannot_resumeinvalid_request_error422Una recurrencia completada no se reanuda ni se activa: ya agotó sus ocurrencias o pasó su fecha de fin, así que no le queda ninguna generación pendiente.
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.
recurring_presentation_activation_changedconflict_error409La empresa cambió de activación del sistema de presentación dos veces seguidas mientras se generaba la factura recurrente. La generación se detuvo sin escribir nada.
recurring_presentation_policy_precondition_requiredinvalid_request_error428El cambio de la política de presentación no indicó sobre qué versión se basa.
recurring_presentation_policy_version_conflictconflict_error409La política de presentación de la recurrencia cambió después de leerla.
recurring_presentation_unavailableinvalid_request_error422Cuando se ejecutó una generación de la recurrencia, la presentación que tiene configurada no estaba disponible, así que no se pudo generar la factura. details.reason indica qué faltaba.

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. También lo devuelve una línea de factura, presupuesto, proforma, albarán o factura recurrente sin tax_rate cuando ni el producto tiene impuesto asignado ni tu empresa tiene un IVA por defecto para ese tipo de documento: error.param es lines.N.tax_rate y error.line_index es la posición (base 0) de esa línea. También lo devuelve POST /v1/companies/{company}/invoices cuando pides el envío por correo (options.send_automatically) y no hay destinatario posible —sin cliente, o con un cliente sin email, y sin options.send_to—: error.param es options.send_to y no se crea ninguna factura.
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, y sale como código principal (400). En las operaciones que validan un formulario o un parámetro de consulta con reglas (por ejemplo format en los PDF de factura) llega como entrada de error.errors[], con su allowed_values, dentro de un 422 invalid_param_value.
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, el page de paginación por offset —v1 pagina por cursor— o una cabecera retirada de la v1.
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_error404El segmento {company} de la ruta nombra una empresa que no existe o que no está en el ámbito de NIFs de la credencial. Ambos casos responden igual para que la API nunca revele empresas de otras cuentas.
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. En POST /v1/companies/{company}/invoices con external_id, otra petición con el MISMO external_id sigue en curso y no terminó tras esperarla 20 segundos.
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, una ruta de otra área de la API o la forma plana de una ruta que la ventana de ruptura trasladó al segmento de empresa o de cuenta; en ese último caso error.subcode vale legacy_route_moved.
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_template_assignmentinvalid_request_error422La asignación de plantilla PDF enviada para la serie es incoherente: la selección o su versión no son válidas.
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_default_kind_changeinvalid_request_error422La serie es la predeterminada de su propósito (invoice_kind): la serie por defecto lo es por empresa, tipo y propósito, así que cambiarle el propósito dejaría ese propósito sin serie predeterminada.
series_format_immutable_with_documentsinvalid_request_error422La máscara de numeración de una serie se puede cambiar hasta la primera emisión: después, el PDF y el registro de la AEAT de los documentos ya emitidos llevan el número con el formato 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_error405Una serie no se elimina por la API: conserva los documentos que numeró y su código no se libera. PUT y DELETE no son operaciones sobre una serie.
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_invoice_kind_invalidinvalid_request_error422El propósito de la serie queda fuera del catálogo complete, simplified, corrective, simplified_corrective, o se ha indicado en una serie que no es de facturas.
series_invoice_kind_lockedinvalid_request_error422El propósito de la serie (invoice_kind) se fija al crearla y deja de ser editable en cuanto tiene alguna factura: cambiarlo mezclaría tipos de factura en una misma numeración correlativa.
series_invoice_kind_mismatchinvalid_request_error422Las series de facturas tienen un propósito fijo (invoice_kind): complete para facturas completas, simplified para simplificadas, corrective para rectificativas y simplified_corrective para rectificativas de simplificadas. Una factura solo se numera en una serie de su mismo propósito (arts. 6.1.a, 7.1.a y 15 del RD 1619/2012), y la serie indicada es de otro.
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_template_access_deniedauthorization_error403La credencial o el usuario no tiene permiso para cambiar la plantilla PDF de esta serie.
series_template_incompatibleinvalid_request_error422La plantilla no admite el tipo de documento, el propósito (invoice_kind) o el formato de numeración de la serie.
series_template_precondition_failedconflict_error412El ETag enviado en If-Match ya no coincide con el recurso de plantilla de la serie, que cambió después de leerlo.
series_template_precondition_requiredinvalid_request_error428El cambio de la plantilla de la serie no indicó la versión o la precondición del recurso en que se basa.
series_template_unavailableinvalid_request_error422La plantilla está archivada o no es seleccionable para esta empresa, así que no puede asignarse a la serie.
series_template_version_conflictconflict_error409La asignación de plantilla PDF de la serie cambió después de leerla.
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 archivo.
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_error402La cuenta ha alcanzado su uso máximo.

Integraciones de tareas

CodeTypeHTTPDescripción
forge_account_link_rejectedinvalid_request_error422Solo se pueden vincular cuentas personales de GitHub. GitLab y Gitea no usan cuentas vinculadas: se conectan con el token de acceso de la integración del proyecto.
forge_account_not_linkedinvalid_request_error422La operación actúa en tu nombre en la forja —por ejemplo, para listar tus repositorios de GitHub— y todavía no has vinculado tu cuenta de esa forja a tu usuario.
forge_credentials_rejectedinvalid_request_error422La instancia de GitLab o Gitea rechaza la dirección o la credencial indicadas. El subcode dice el motivo: not_a_forge_instance, redirected, repository_not_found, insufficient_permissions o unauthorized.
forge_oauth_state_invalidinvalid_request_error422La vinculación con la forja no se ha podido completar: el estado de la autorización ha caducado, ya se usó, no es válido o pertenece a otro usuario o empresa.
forge_repository_access_deniedauthorization_error403Tu cuenta de GitHub vinculada no permite conectar ese repositorio, o el repositorio no existe; la respuesta es la misma en ambos casos para no revelar repositorios ajenos.
forge_repository_bound_elsewhereconflict_error409El repositorio ya está conectado a otro proyecto activo de la empresa. Un repositorio alimenta un único proyecto, para que cada issue o pull request acabe en una sola tarea.
forge_secret_rotation_not_supportedinvalid_request_error422Esta integración no tiene un secreto de webhook propio que rotar: las de GitHub firman con el secreto de la GitHub App, y la rotación solo existe en las integraciones de GitLab y Gitea.
forge_token_requiredinvalid_request_error422Se cambia la URL de la instancia de la forja sin aportar un token nuevo. El token guardado nunca se envía a una dirección distinta de aquella para la que se dio, para que no acabe en un servidor ajeno.
forge_webhook_signature_invalidauthentication_error401La entrega de webhook de la forja no se ha podido autenticar: la firma no coincide con el secreto de la integración, o la integración no existe. No se ha procesado ningún evento.
forge_workflow_rule_column_invalidinvalid_request_error422La columna de destino de la regla no pertenece al proyecto de la integración; una columna inexistente, de otro proyecto o de otra empresa responden igual.
forge_workflow_rule_not_foundnot_found_error404La regla que mueve tareas de columna ante un evento de la forja (por ejemplo, al fusionar una pull request) no existe o es de otra empresa; los dos casos responden igual.
github_app_not_configuredinvalid_request_error422La integración con GitHub no está disponible en este servidor porque su administrador no ha configurado la GitHub App. No es un problema de tu cuenta ni de tus permisos.
import_credentials_rejectedinvalid_request_error422El sistema de origen de la importación ha rechazado las credenciales aportadas con una respuesta de no autorizado o prohibido. No se ha importado nada.
import_run_already_activeconflict_error409Ya hay una importación en curso desde el mismo origen hacia el mismo destino. Dos importaciones simultáneas crearían tareas duplicadas, así que la segunda no se lanza.
integration_destination_not_allowedinvalid_request_error422La política de salida de la empresa no permite conectar con esa dirección: por seguridad, los destinos privados o internos se bloquean salvo que la empresa los haya autorizado. El error no repite la URL rechazada.
project_integration_already_connectedconflict_error409El proyecto ya tiene una integración de ese tipo, o ya está conectado a otro repositorio. Cada proyecto admite una sola integración por tipo, para que los eventos no se dupliquen.
project_integration_not_foundnot_found_error404La integración del proyecto no existe o es de otra empresa; los dos casos responden igual. Las integraciones de forjas y chats solo se gestionan desde la aplicación web, no desde la API v1.
task_import_run_not_foundnot_found_error404La importación indicada no existe o es de otra empresa; los dos casos responden igual. Cada importación tiene su propio identificador, distinto del del proyecto de destino.

Tareas

CodeTypeHTTPDescripción
bulk_task_selection_too_largeinvalid_request_error422La operación masiva incluye más tareas de las que admite un solo lote (200 por defecto; el mensaje dice el tope vigente). No es un límite de peticiones ni del plan: acota lo que se procesa de una vez.
column_has_tasksconflict_error409La columna que intentas borrar todavía tiene tareas y la petición no dice adónde llevarlas. Para no dejar tareas sin sitio en el tablero, el borrado se rechaza y no se ha modificado nada.
column_slug_in_useconflict_error409Otra columna del mismo proyecto ya tiene un nombre equivalente. Se compara el identificador que se deriva del nombre, así que dos nombres que solo difieren en mayúsculas o signos chocan igual.
column_slug_reservedinvalid_request_error422El nombre de la columna se traduce al identificador planned o archived, reservados para los estados de las tareas que están fuera del tablero. Una columna así sería indistinguible de esos estados.
invalid_custom_field_definitioninvalid_request_error422La definición del campo personalizado no es válida: nombre fuera de 1 a 60 caracteres, tipo desconocido, campo obligatorio sin valor por defecto, opciones en un tipo que no las admite, cambio de tipo tras crearlo, quitar una opción que usan tareas, o una reordenación incompleta. error.param señala el dato concreto.
invalid_custom_field_valueinvalid_request_error422El valor no encaja con el tipo del campo personalizado —por ejemplo, texto en un campo numérico u opción que no está en la lista— o el campo no pertenece al proyecto de la tarea.
invalid_move_target_columninvalid_request_error422La columna indicada para recibir las tareas no sirve de destino: no existe, es de otro proyecto o es la misma columna que se está borrando. El borrado no se ha hecho.
invalid_task_keyinvalid_request_error422La clave de tarea no tiene la forma CLAVE-N —clave del proyecto, guion y número, como WEB-42— o el número de tarea no es un entero positivo.
invalid_task_referenceinvalid_request_error422Una tarea referenciada en el cuerpo de la petición no existe o es de otra empresa; los dos casos responden igual. error.param indica qué campo contenía la referencia.
invalid_task_scheduleinvalid_request_error422Las fechas de la tarea no son coherentes: la fecha de inicio es posterior a la fecha límite, o una de las dos no existe en el calendario (por ejemplo, un 30 de febrero).
invalid_task_statusinvalid_request_error422El destino de la tarea no es válido: el estado no existe, la transición no está permitida, se envían a la vez columna y estado, la columna no es del proyecto de la tarea, o se pide columna para una tarea planificada o archivada. Una tarea en el tablero siempre tiene columna y una fuera de él nunca la tiene.
invalid_time_entry_periodinvalid_request_error422El periodo de la entrada de tiempo no es válido: el fin es anterior al inicio, dura más de 24 horas, el inicio está más de un día en el futuro, una fecha no es válida, se intenta quitar el fin de una entrada cerrada o se cambian las horas de una entrada que sigue en marcha.
limit_exceededpayment_required_error402La empresa ha alcanzado el límite de facturas o de documentos anuales de su plan; el mensaje dice cuál. En la API v1 lo emite la facturación de horas (POST /v1/companies/{company}/projects/{project}/time-invoices), que lo comprueba antes de crear nada: no se ha generado el borrador de factura ni se ha marcado ninguna hora como facturada.
linked_entity_not_foundnot_found_error404La entidad que se quiere vincular no existe, es de otra empresa o pertenece a un módulo que la empresa no tiene contratado; los tres casos responden igual. Ocurre al vincular (POST /v1/companies/{company}/tasks/{task}/entity-links) y también al crear una tarea con entity_link en POST /v1/companies/{company}/tasks: en ese caso la tarea NO se crea.
project_archivedinvalid_request_error422El proyecto está archivado y no admite tareas nuevas ni que se muevan tareas hacia él. Archivar congela el proyecto sin borrarlo.
project_column_not_foundnot_found_error404La columna no existe, pertenece a otro proyecto o es de otra empresa; los tres casos responden igual. Una columna solo se direcciona dentro del proyecto que la contiene.
project_has_no_columnsinvalid_request_error422Se pide colocar la tarea en el tablero, pero el proyecto no tiene ninguna columna en la que ponerla. Una tarea activa siempre vive en una columna.
project_key_in_useconflict_error409La clave corta ya la usa otro proyecto de la empresa, o sigue reservada como clave anterior de un proyecto que la cambió. La clave da nombre a las tareas (WEB-42), así que no puede repetirse dentro de la empresa.
project_not_foundnot_found_error404No existe ningún proyecto con ese identificador o esa clave en la empresa autenticada. Un proyecto de otra empresa responde exactamente igual, así que la respuesta nunca revela si existe en otro sitio.
required_custom_field_missinginvalid_request_error422Falta el valor de un campo personalizado que el proyecto declara obligatorio; el mensaje nombra el campo. Un campo obligatorio no puede quedar vacío.
task_already_in_projectinvalid_request_error422Se pide trasladar la tarea al proyecto en el que ya está, así que no hay traslado que hacer.
task_assignee_not_memberinvalid_request_error422El usuario indicado como asignado no es miembro de la empresa. Un usuario inexistente, de otra empresa o sin membresía responden igual, para no revelar cuentas ajenas.
task_attachment_not_foundnot_found_error404El adjunto no existe, pertenece a otra tarea o es de otra empresa; los tres casos responden igual. Un adjunto borrado deja de poder consultarse y descargarse.
task_attachment_rejectedinvalid_request_error422El fichero no se admite como adjunto: está vacío, supera los 10 MB, o su tipo real —detectado por su contenido (magic bytes), no por la extensión ni por la cabecera— no está permitido. También se rechaza una surface distinta de description o comment.
task_calendar_feed_not_foundnot_found_error404El feed de calendario (iCal) no existe, está revocado, es de otra empresa o es el feed personal de otro usuario; todos los casos responden igual. Solo lo emite la aplicación web al rotar o revocar feeds, no la API v1.
task_column_capacity_exceededconflict_error409El ámbito del tablero —la columna, o el estado planificado o archivado— ha agotado el rango de posiciones con que se ordenan sus tareas. No es un límite del plan ni de permisos, sino el tope técnico de ordenación de ese ámbito.
task_comment_not_editableinvalid_request_error422El comentario no se puede editar: solo su autor puede modificarlo, y los comentarios importados o traídos por una integración son inmutables para conservar lo que dijo el origen.
task_comment_not_foundnot_found_error404El comentario no existe, pertenece a otra tarea o es de otra empresa; los tres casos responden igual. Un comentario solo se direcciona bajo la tarea en la que se escribió.
task_custom_field_not_foundnot_found_error404El campo personalizado no existe, pertenece a otro proyecto o es de otra empresa; los tres casos responden igual. Cada proyecto define sus propios campos.
task_description_too_largeinvalid_request_error422La descripción supera el máximo de 100.000 caracteres, contados sobre el Markdown enviado antes de sanearlo. El tope no depende del plan: protege el editor y el almacenamiento.
task_entity_link_not_foundnot_found_error404El vínculo entre la tarea y un documento, contacto, producto o empleado no existe, pertenece a otra tarea o es de otra empresa; los tres casos responden igual.
task_external_link_not_foundnot_found_error404El enlace externo no existe, pertenece a otra tarea o es de otra empresa. También responde así un enlace que mantiene una integración (una issue o una pull request de la forja) cuando se intenta gestionar como si fuera un enlace manual.
task_label_name_in_useconflict_error409Ya existe en la empresa una etiqueta con ese nombre; la comparación no distingue mayúsculas de minúsculas. Las etiquetas se comparten entre todos los proyectos de la empresa.
task_label_not_foundnot_found_error404No existe ninguna etiqueta con ese identificador en la empresa autenticada; una etiqueta de otra empresa responde igual. Las etiquetas son de la empresa, no de un proyecto concreto.
task_not_foundnot_found_error404No existe ninguna tarea con ese identificador o esa clave en la empresa autenticada. Una tarea de otra empresa —o, en el portal del empleado, una que no tiene asignada— responde exactamente igual.
task_relation_cycleinvalid_request_error422La relación cerraría un ciclo de subtareas o de bloqueos: la tarea destino ya depende, directa o indirectamente, de la de origen, y ninguna de las dos podría completarse primero.
task_relation_existsconflict_error409Entre estas dos tareas ya hay una relación del mismo tipo, en cualquiera de las dos direcciones. Repetirla no añadiría información, así que no se crea una segunda.
task_relation_not_foundnot_found_error404No existe ninguna relación con ese identificador entre tareas de la empresa autenticada; una relación de otra empresa, o una ya borrada, responde igual.
task_self_relationinvalid_request_error422La tarea de origen y la de destino son la misma, y una tarea no puede relacionarse consigo misma.
task_time_entry_invoicedinvalid_request_error422La entrada de tiempo ya está incluida en una factura. Mientras siga vinculada no se edita ni se vuelve a facturar, para que la factura y las horas no se contradigan.
task_time_entry_not_foundnot_found_error404La entrada de tiempo no existe, pertenece a otra tarea o es de otra empresa; los tres casos responden igual.
task_time_not_invoiceableinvalid_request_error422No se pueden facturar las horas pedidas y el mensaje nombra el motivo: el proyecto no tiene cliente de facturación o ese cliente ya no admite facturas, falta tarifa por hora o producto con precio, una entrada no es facturable, está en marcha o es de otro proyecto, no hay entradas facturables, o la selección es ambigua.
task_timer_already_runningconflict_error409Ya tienes un temporizador en marcha en esta empresa. Cada usuario puede tener como máximo uno a la vez por empresa, para que el tiempo registrado no se solape entre tareas.
task_timer_not_runninginvalid_request_error422Se pide parar el temporizador, pero no tienes ninguno en marcha en esta empresa; puede que ya se parara desde otra sesión o dispositivo.
task_upload_link_expiredinvalid_request_error410El enlace de subida ya no sirve. El subcode dice por qué: expired, porque el enlace caducó (vive 30 minutos desde que se creó), o consumed, porque ya se usó una vez y cada enlace admite un único envío.
task_upload_link_not_foundnot_found_error404El enlace de subida no es válido: el token está mal formado o no corresponde a ningún enlace, casi siempre porque se copió incompleto. Un enlace caducado o ya usado responde en cambio con task_upload_link_expired.

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
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.
global_tax_read_onlyauthorization_error403El impuesto pertenece al catálogo de Factuarea, que es de solo lectura para las empresas: solo puedes modificar o eliminar los impuestos que creó tu propia empresa.
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_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_default_axis_disabledinvalid_request_error422El impuesto no puede fijarse como predeterminado porque su tipo (IVA, retención o recargo) está desactivado en la empresa para el documento pedido, o en todos los documentos a los que se aplicaría si no indicas ninguno.
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_defaultable_for_documentinvalid_request_error422El impuesto no puede ser el predeterminado de ese documento: es de tipo other, su ámbito (applies_to) no cubre el documento o el documento es recurring_invoice, que hereda de factura.
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.

Control horario

CodeTypeHTTPDescripción
clocking_outside_employment_periodinvalid_request_error422El instante del fichaje cae antes de la fecha de alta del empleado o después de su fecha de baja, así que no se ha escrito nada en el registro horario. El día de alta y el día de baja sí admiten fichaje. Al aprobar una corrección se vuelve a comprobar el periodo de alta vigente, y una aprobación rechazada deja la solicitud pendiente.

Documentos de control

CodeTypeHTTPDescripción
delivery_note_cancelledinvalid_request_error422Uno de los albaranes enviados para prerrellenar el documento de control está anulado, y un albarán anulado no puede ser origen de un envío. No se ha creado nada.
invalid_cargo_measureinvalid_request_error422La magnitud declarada de un envío no es válida: su type no es weight ni other, falta el peso o el valor o no es mayor que cero, o la unidad libre no tiene entre 1 y 30 caracteres.
invalid_transport_tax_idinvalid_request_error422La identificación fiscal de una parte no es válida: un NIF, NIE o CIF español con el carácter de control erróneo, o un identificador extranjero fuera de 2 a 20 caracteres alfanuméricos.
invalid_vehicle_plateinvalid_request_error422Una matrícula no encaja en un formato español (actual, provincial antigua, remolque R, especial E o histórica H; las españolas no llevan vocales) ni en una extranjera de 2 a 12 caracteres alfanuméricos con su país.
transport_date_in_pastinvalid_request_error422Un documento de control se emite antes de iniciar el transporte, y una de las fechas de transporte es anterior a hoy (Europe/Madrid). El borrador admite cualquier fecha; la emisión no.
transport_document_cannot_be_cancelledinvalid_request_error422Solo se puede anular un documento de control emitido y en curso; un borrador se borra, y uno cerrado, anulado o sustituido no se anula.
transport_document_cannot_be_closedinvalid_request_error422Solo se puede cerrar un documento de control emitido; este es un borrador o ya está cerrado, anulado o sustituido.
transport_document_cannot_be_deletedinvalid_request_error422Solo se puede borrar un borrador: un documento de control emitido se conserva como prueba durante todo su plazo de conservación.
transport_document_cannot_be_editedinvalid_request_error422Solo un documento de control en borrador se puede editar; este ya está emitido, cerrado, anulado o sustituido.
transport_document_cannot_be_modifiedinvalid_request_error422Solo se puede modificar un documento de control emitido, y la modificación debe dejarlo con todos los datos obligatorios y al menos un envío.
transport_document_cannot_be_reopenedinvalid_request_error422Solo se puede reabrir un documento de control cerrado a mano, y solo antes de su plazo de cierre automático; tras un cierre automático queda cerrado.
transport_document_cannot_be_supersededinvalid_request_error422Solo se puede marcar como sustituido por el documento del transportista un documento de control emitido y en curso.
transport_document_file_unavailablenot_found_error410Los PDF de este documento de control se purgaron al terminar su plazo de conservación (un año tras cerrarlo, anularlo o sustituirlo, y solo porque la cuenta está cerrada). El documento y sus datos se conservan.
transport_document_no_changesinvalid_request_error422La modificación trae exactamente los mismos datos que la versión vigente, así que no hay versión nueva que publicar.
transport_document_not_foundnot_found_error404El identificador no resuelve a ningún documento de control de la empresa autenticada, o el token público no existe.
transport_document_not_issuableinvalid_request_error422El documento no se puede emitir: no es un borrador o le faltan datos obligatorios del art. 6 de la Orden FOM/2861/2012 (partes, NIF, domicilio del cargador, envíos con origen, destino, mercancía y magnitud, matrícula de la tractora o fecha de transporte).
transport_document_not_sendableinvalid_request_error422No se puede enviar el documento por email: no está emitido ni cerrado, no hay destinatario (sin to y el contacto transportista sin email) o to, cc y bcc suman más de 5 direcciones.
transport_document_parties_immutableinvalid_request_error422Tras emitir, el cargador contractual y el transportista efectivo quedan fijados: la norma no permite cambiarlos en una modificación.
transport_document_pdf_too_largeinvalid_request_error422El PDF de la versión superaría los 5 MB (5.000.000 bytes) que permite la normativa por la cantidad de datos del documento: envíos, líneas de mercancía, descripciones u observaciones. No se ha guardado nada.
transport_document_version_limit_reachedinvalid_request_error422Un documento de control admite como máximo 50 versiones y la última se reserva para anularlo o sustituirlo, así que ya no admite más modificaciones. No se ha guardado nada.
transport_document_version_not_foundnot_found_error404El documento de control existe, pero no tiene la versión pedida en version: sus versiones van de la 1 a la vigente (current_version).
transport_outside_spaininvalid_request_error422El documento de control solo cubre transporte interior, y un envío sale o llega fuera de España. El transporte internacional se documenta con la carta de porte CMR.

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.
chain_position_conflictconflict_error409Dos registros de la misma empresa intentaron tomar a la vez la misma posición de la cadena de huellas y los reintentos automáticos no resolvieron la colisión.
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.
invalid_representationinvalid_request_error422La representación incumple una regla: falta el anexo I firmado o el justificante del apoderamiento, el documento no es un PDF válido o supera los 5 MB, signer_name, power_of_attorney_reference o el motivo de la revocación (reason, de 3 a 500 caracteres) no respetan su longitud, valid_until es anterior a granted_on o la supera en más de 5 años, o la representación ya está revocada (o no hay ninguna vigente que revocar).
max_retries_exceededinvalid_request_error422Solo aplica a los EVENTOS del modo NO VERI*FACTU (POST /v1/companies/{company}/verifactu/events/{id}/retry): el evento agotó su tope de intentos de transmisión. Los registros de facturación NO tienen tope de reintentos —el art. 16.4 de la Orden HAC/1177/2024 exige reintentar al menos una vez por hora mientras dure la incidencia—, así que ningún reintento de un registro devuelve ya este código.
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_error422Solo se puede subsanar un registro de alta que la AEAT aceptó (o aceptó con errores) o rechazó. Este registro está en otro estado —pendiente de remitir, enviado sin respuesta o en error técnico—, que cubre el reintento y no la subsanación.
record_not_subsanableinvalid_request_error422El registro no admite subsanación: no es un registro de alta, no es el ÚLTIMO alta de su factura (otra subsanación posterior lo sustituye), la factura está anulada, es un rechazado cuya alta corregida ya espera reenviarse, o no tiene factura de origen desde la que regenerar sus datos.
representation_requiredinvalid_request_error422El modo de remisión pide a Factuarea que remita tus registros a la AEAT en tu nombre, y la empresa no tiene una representación vigente —ni revocada ni caducada— del tipo que ese modo necesita (el anexo I firmado para social_collaborator, el apoderamiento inscrito para power_of_attorney).
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.
signing_certificate_unavailableinvalid_request_error422La empresa tiene VeriFactu activado en modo NO VERI*FACTU, donde cada registro de facturación se firma (Orden HAC/1177/2024, arts. 6.c y 14), y no hay con qué firmarlo. error.param dice QUÉ falta, y es estable: certificate = el certificado de la empresa falta, está caducado o revocado, lleva el NIF de otra empresa o su archivo .p12 no se puede leer (dañado, o con una contraseña guardada que ya no es válida); representation = en los modos de remisión por tercero, la representación que habilita a Factuarea a firmar en nombre de la empresa no está activa; system_certificate = el certificado de Factuarea no está disponible o no se puede leer. Sin firma no existe registro válido, y una factura emitida o anulada no puede quedar sin el suyo, así que la operación se rechaza antes de ejecutarse.
sii_excludedinvalid_request_error422La empresa está registrada en el SII, y los obligados al SII quedan excluidos del reglamento VeriFactu.
social_collaborator_unavailableinvalid_request_error422El acuerdo de colaboración social con la AEAT aún no está en vigor en esta instancia, así que no se puede elegir el modo social_collaborator.
system_certificate_unavailableapi_error500El certificado de Factuarea que remite los registros en los modos de tercero falta, ha caducado o ha sido revocado. Es un problema nuestro, no de tu petición.
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. Al emitir o anular, el mismo código con el subcódigo signing_certificate_unavailable indica que la empresa, con VeriFactu activado en modo NO VERI*FACTU, no tiene con qué firmar el registro (error.param: certificate, representation o system_certificate, según lo que falte), y con otros error.param que un dato de la factura no cabe en el registro de alta (lee error.param y error.message).
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
account_webhook_endpoint_limit_reachedinvalid_request_error422La cuenta alcanzó el número de endpoints de webhook de cuenta que permite su tramo en ese entorno. El tope se cuenta por cuenta y por entorno (live o test) e incluye los endpoints desactivados: solo se libera una plaza al borrar un endpoint.
addon_requiredpayment_required_error402Crear endpoints de webhook exige un plan que los incluya: en los de empresa, el add-on Developer API de la empresa; en los de cuenta, el plan del pagador de la cuenta. Aquí falta esa contratación: 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_rotatedinvalid_request_error422El 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. Se responde como un 422 business_rule_violation con error.subcode webhook_secret_recently_rotated; no es un límite de peticiones y no consume ningún cubo de rate limit.
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ónAutomatizacionesFacturaciónEmpresasContactosAlbaranesEmpleadosEventsExportacionesEmpresas gestionadasIdempotencyIntegracionesFacturasMCPNotificacionesPagosPDFTarifasProductosFacturas proformaGastosEscáner de gastosPresupuestosLímite de tasaFacturas recurrentesRequestSeriesServidorAlmacenamientoIntegraciones de tareasTareasInformes fiscalesImpuestosControl horarioDocumentos de controlVeriFactuWebhooks
¿Te echamos una mano?Contactar con soporte