Errores de Verifactu: qué significan y cómo resolverlos
Al enviar una factura a Verifactu con la API Verifactu puedes encontrar tres tipos de error: el de la petición (HTTP 400 sin codigo, 401, 403, 409 o 422), el de la validación previa de Verifacti (HTTP 400 con un código estable vf-verifactu-…; la factura no llega a la AEAT) y el que devuelve la AEAT al procesar el registro, que ves en el estado (Aceptado con errores, Incorrecto…) con su codigo_error y mensaje_error.
Los tres tipos de error
| Tipo | Cuándo | Dónde lo ves | Qué hacer |
|---|---|---|---|
| Error de la petición | La API no acepta la llamada (API key, NIF desactivado, modelo de representación, idempotencia) | HTTP 400 sin codigo, 401, 403, 409 o 422 | Corregir la llamada y repetir |
| Error de validación de la API | Los datos de la factura no son válidos | HTTP 400 con error y codigo (vf-verifactu-…) | Corregir los datos; el registro no se ha creado |
| Error de la AEAT | La AEAT procesa el registro y detecta un problema | estado, codigo_error y mensaje_error en GET /verifactu/status o en el webhook | Subsanar, rectificar o revisar según el estado |
Errores de validación de la API
Antes de enviar nada a la AEAT, la API valida los datos de la factura con sus reglas. Si algo no es válido, responde 400 con una descripción en español (error) y un código estable (codigo), y el registro no se crea. Programa contra codigo (no cambia nunca de significado) y deja una rama por defecto que muestre error: el catálogo crece cuando se añaden reglas.
{
"error": "El campo tipo_factura debe ser F1, F2, R1, R2, R3, R4, R5 o F3.",
"codigo": "vf-verifactu-tipo_factura_valor"
}| Código | Mensaje |
|---|---|
vf-verifactu-fecha_expedicion_hoy | El campo fecha_expedicion debe ser la fecha actual. |
vf-verifactu-fecha_expedicion_formato_rango | El campo fecha_expedicion debe tener el formato DD-MM-YYYY y ser una fecha válida. No puede ser una fecha posterior a la actual ni anterior a 28-10-2024. |
vf-verifactu-importe_total_cuadre | El campo importe_total debe ser igual a la suma de los campos base_imponible, cuota_repercutida y cuota_recargo_equivalencia de todas las lineas con un margen de error de 10 euros. |
vf-verifactu-importe_total_decimales | El campo importe_total debe ser un número con 2 decimales como máximo. Los decimales deben ser separados con un punto. |
vf-verifactu-factura_duplicada | Ya existe una factura con la misma serie, numero y fecha_expedicion. |
vf-verifactu-serie_numero_longitud | La concatenacion de serie y numero no puede tener mas de 60 caracteres. |
vf-verifactu-f2_limite_3000 | Cuando tipo_factura sea F2 y factura_sin_identif_destinatario_art_61d no sea S, el sumatorio de base_imponible y cuota_repercutida de todas las lineas no puede ser superior a 3000 euros. |
vf-verifactu-destinatario_no_aplica | Para facturas de tipo F2 y R5 no se pueden indicar los campos nombre, nif o id_otro. |
vf-verifactu-nif_formato | El campo nif no tiene un formato válido. |
El catálogo completo de la API Verifactu (155 códigos a 18 de noviembre de 2026) está en codigos-verifactu.yaml.
Estados del registro
GET /verifactu/status?uuid=… y los webhooks dan el estado del registro de facturación (no necesariamente el de la factura: una factura puede tener varios registros).
| Estado | Qué significa | Qué hacer |
|---|---|---|
Pendiente | Encolado, aún no enviado a la AEAT | Esperar (normalmente uno o dos minutos) o recibirlo por webhook |
Correcto | Registrado por la AEAT | Nada |
Aceptado con errores | Registrado por la AEAT, con errores | Subsanación con PUT /verifactu/modify o factura rectificativa |
Incorrecto | Rechazado por la AEAT: el registro no consta | PUT /verifactu/modify con rechazo_previo X si se rechazó el alta, o S si se rechazó una subsanación |
Duplicado | Ya existe un registro con la misma serie, numero y fecha_expedicion | Revisar la numeración |
Anulado | Anulación registrada | Nada |
Factura inexistente | La AEAT ha rechazado la anulación (por ejemplo, porque la factura no consta) | Revisar los datos o anular sin registro previo |
No registrado | La AEAT ha rechazado el envío completo | Revisar el error, corregir y reenviar |
Error servidor AEAT | Error en la AEAT | Nada: Verifacti reenvía el registro |
Errores que devuelve la AEAT
Cuando la AEAT detecta un problema, GET /verifactu/status y el webhook incluyen codigo_error y mensaje_error tal como los da la AEAT. Cada código, con la validación que lo provoca, está en el documento de validaciones y errores de la AEAT (v1.2.2), que también separa los errores que rechazan el registro de los que lo admiten con errores. La lista de códigos está en la página de validaciones y errores del portal de desarrolladores.
Factura aceptada con errores: qué hacer
Aceptado con errores: la AEAT ha registrado la factura, pero ha detectado errores. Envía una subsanación conPUT /verifactu/modifyo emite una factura rectificativa, según si el error es del registro o de la factura.Incorrecto: la factura no consta en la AEAT. Envía la subsanación conrechazo_previo(Xsi se rechazó el alta;Ssi se rechazó una subsanación).Duplicado: ya existe un registro con la mismaserie,numeroyfecha_expedicion. Revisa la numeración antes de reenviar.
Reintentar sin duplicar
Usa el header Idempotency-Key en /create, /create_bulk, /modify y /cancel, con la misma clave en todos los reintentos de una factura. Cómo hacerlo en tu lenguaje, en los tutoriales por lenguaje.
- Un reintento con la misma clave y el mismo cuerpo devuelve la primera respuesta, con
Idempotent-Replayed: true, sin crear otro registro. Error servidor AEATno necesita reintento por tu parte: Verifacti reenvía el registro.- La
Idempotency-Keyse guarda 24 horas: pasado ese plazo, antes de reintentar comprueba conPOST /verifactu/status(serie,numeroyfecha_expedicion) si la factura llegó a registrarse.
{
"error": "idempotent_request_in_progress",
"message": "Otra petición con esta Idempotency-Key se está procesando. Reintente en unos segundos."
}{
"error": "Esta Idempotency-Key ya se usó con un payload distinto. Use una clave nueva."
}| HTTP | Causa | Qué hacer |
|---|---|---|
| 400 (sin codigo) | Petición rechazada antes de validar la factura: en producción, modelo de representación sin firmar; endpoint de otra hacienda; Idempotency-Key mal formada | Leer error y corregir la llamada |
| 401 | API key ausente o no válida | Revisar el header Authorization |
| 403 | NIF desactivado | Activarlo en el panel o con la API de gestión de NIFs |
| 400 | Datos no válidos (codigo vf-verifactu-…) | Corregir y reenviar con una Idempotency-Key nueva |
| 409 | Otra petición con la misma Idempotency-Key en curso | Esperar unos segundos y repetir |
| 422 | Idempotency-Key reutilizada con otro cuerpo | Usar una clave nueva |
| 429 | Demasiadas peticiones con la misma API key | Esperar y reintentar con menos frecuencia |
| 5xx | Error de servidor | Reintentar con la misma Idempotency-Key |
Cómo prevenir errores
- Prueba cada tipo de factura en el entorno de test antes de pasar a producción, partiendo de los ejemplos de Verifactu.
- Deja que la API compruebe el NIF del destinatario en el censo de la AEAT (lo hace por defecto; en el entorno de test puedes desactivarlo con
validar_destinatario: false, en producción se comprueba siempre), o pruébalo antes con el comprobador de NIF. - Comprueba que
importe_totalcuadra con las líneas y que, en el entorno de test,fecha_expediciones la de hoy. - Si generas el XML tú mismo, pásalo por el validador de XML de Verifactu o valídalo contra los XSD (cómo).
Siguiente paso
La API Verifactu valida los datos antes de enviarlos a la AEAT y te devuelve cada error de validación con un código estable. Empieza con la guía rápida o la documentación.
Otros tutoriales de Verifactu
Preguntas sobre los errores de Verifactu
Más preguntas sobre la API Verifactu¿Qué diferencia hay entre un 400 de la API y un error de la AEAT?
400 lo devuelve Verifacti antes de enviar nada: el registro no se crea. El error de la AEAT llega después, en el estado del registro, con codigo_error y mensaje_error.¿Una factura «Aceptado con errores» está registrada?
¿Dónde está la lista de códigos de error?
¿Cómo reintento sin duplicar una factura?
Idempotency-Key: la misma clave y el mismo cuerpo devuelven la primera respuesta sin crear otro registro.¿Los códigos vf-verifactu pueden cambiar?
error.Prueba los errores en el entorno de test
Con la cuenta gratuita ves los errores antes de que lleguen a producción.