Códigos de error de VeriFactu

Códigos de error que emite VeriFactu. Cada code enlaza a su propia página con la causa y la acción a tomar.

Code	Type	HTTP	Descripción
`alta_record_not_found`	`not_found_error`	404	La factura no tiene registro de alta, así que la operación que depende de él no tiene sobre qué trabajar.
`anulacion_record_already_exists`	`conflict_error`	409	La factura ya tiene un registro de anulación en la cadena, y la anulación se declara una sola vez.
`certificate_expired`	`invalid_request_error`	422	El certificado está fuera de su ventana de validez: ha caducado, o todavía no es válido.
`certificate_nif_mismatch`	`invalid_request_error`	422	El 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_found`	`not_found_error`	404	La empresa no tiene ningún certificado FNMT que corresponda al identificador, o no tiene ninguno subido.
`certificate_too_large`	`invalid_request_error`	422	El fichero supera el límite de 100 KB, cuando un certificado FNMT real pesa unos pocos kilobytes.
`chain_position_conflict`	`conflict_error`	409	Dos 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_exceeded`	`invalid_request_error`	422	El 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_exists`	`conflict_error`	409	La empresa ya tiene presentada la declaración responsable del SIF de ese período.
`declaracion_not_found`	`not_found_error`	404	La empresa no tiene presentada la declaración responsable del SIF del período solicitado.
`event_already_processed`	`invalid_request_error`	422	Ese evento del SIF ya está registrado en la cadena de eventos, y cada evento se procesa exactamente una vez.
`invalid_certificate_format`	`invalid_request_error`	422	El 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_password`	`invalid_request_error`	422	La contraseña no abre el fichero del certificado.
`invalid_representation`	`invalid_request_error`	422	La 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_exceeded`	`invalid_request_error`	422	Solo 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_end`	`invalid_request_error`	422	El 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_accepted`	`invalid_request_error`	422	La AEAT ya aceptó el registro. La aceptación es terminal y su contenido queda congelado como parte de la cadena de huellas.
`record_immutable`	`invalid_request_error`	422	El registro pertenece a un ledger de solo-adición: una vez escrito, su contenido fiscal queda cerrado a modificaciones y a borrado.
`record_not_rejected`	`invalid_request_error`	422	Solo 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_subsanable`	`invalid_request_error`	422	El 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_required`	`invalid_request_error`	422	El 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_annulment`	`invalid_request_error`	422	El 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_unavailable`	`invalid_request_error`	422	La 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_excluded`	`invalid_request_error`	422	La empresa está registrada en el SII, y los obligados al SII quedan excluidos del reglamento VeriFactu.
`social_collaborator_unavailable`	`invalid_request_error`	422	El 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_unavailable`	`api_error`	500	El 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_submitted`	`invalid_request_error`	422	La 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_invalid`	`invalid_request_error`	422	El modo queda fuera del catálogo `verifactu` / `no_verifactu`.
`verifactu_not_eligible`	`invalid_request_error`	422	La 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_found`	`not_found_error`	404	El identificador no corresponde a ningún registro de facturación de la empresa autenticada.
`verifactu_transmission_failed`	`invalid_request_error`	422	El envío del registro a la AEAT no llegó a completarse: el endpoint estaba inaccesible o respondió con una incidencia.

Relacionado

Códigos de error por categoría

Localiza un error por la categoría que lo emite.

Tabla de referencia completa

Todos los códigos, estados HTTP, tipos y descripciones en una referencia.

Modelo de errores

Interpreta la respuesta de error y gestiona los errores por código.

Códigos de error de VeriFactu

Relacionado

En esta página