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

Tipos de error al enviar facturas con la API Verifactu
TipoCuándoDónde lo vesQué hacer
Error de la peticiónLa API no acepta la llamada (API key, NIF desactivado, modelo de representación, idempotencia)HTTP 400 sin codigo, 401, 403, 409 o 422Corregir la llamada y repetir
Error de validación de la APILos datos de la factura no son válidosHTTP 400 con error y codigo (vf-verifactu-…)Corregir los datos; el registro no se ha creado
Error de la AEATLa AEAT procesa el registro y detecta un problemaestado, codigo_error y mensaje_error en GET /verifactu/status o en el webhookSubsanar, 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.

Respuesta · 400
{
  "error": "El campo tipo_factura debe ser F1, F2, R1, R2, R3, R4, R5 o F3.",
  "codigo": "vf-verifactu-tipo_factura_valor"
}
Errores de validación frecuentes de la API Verifactu
CódigoMensaje
vf-verifactu-fecha_expedicion_hoyEl campo fecha_expedicion debe ser la fecha actual.
vf-verifactu-fecha_expedicion_formato_rangoEl 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_cuadreEl 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_decimalesEl 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_duplicadaYa existe una factura con la misma serie, numero y fecha_expedicion.
vf-verifactu-serie_numero_longitudLa concatenacion de serie y numero no puede tener mas de 60 caracteres.
vf-verifactu-f2_limite_3000Cuando 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_aplicaPara facturas de tipo F2 y R5 no se pueden indicar los campos nombre, nif o id_otro.
vf-verifactu-nif_formatoEl 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).

Estados de un registro de facturación en la API Verifactu
EstadoQué significaQué hacer
PendienteEncolado, aún no enviado a la AEATEsperar (normalmente uno o dos minutos) o recibirlo por webhook
CorrectoRegistrado por la AEATNada
Aceptado con erroresRegistrado por la AEAT, con erroresSubsanación con PUT /verifactu/modify o factura rectificativa
IncorrectoRechazado por la AEAT: el registro no constaPUT /verifactu/modify con rechazo_previo X si se rechazó el alta, o S si se rechazó una subsanación
DuplicadoYa existe un registro con la misma serie, numero y fecha_expedicionRevisar la numeración
AnuladoAnulación registradaNada
Factura inexistenteLa AEAT ha rechazado la anulación (por ejemplo, porque la factura no consta)Revisar los datos o anular sin registro previo
No registradoLa AEAT ha rechazado el envío completoRevisar el error, corregir y reenviar
Error servidor AEATError en la AEATNada: 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 con PUT /verifactu/modify o 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 con rechazo_previo (X si se rechazó el alta; S si se rechazó una subsanación).
  • Duplicado: ya existe un registro con la misma serie, numero y fecha_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 AEAT no necesita reintento por tu parte: Verifacti reenvía el registro.
  • La Idempotency-Key se guarda 24 horas: pasado ese plazo, antes de reintentar comprueba con POST /verifactu/status (serie, numero y fecha_expedicion) si la factura llegó a registrarse.
Respuesta · 409
{
  "error": "idempotent_request_in_progress",
  "message": "Otra petición con esta Idempotency-Key se está procesando. Reintente en unos segundos."
}
Respuesta · 422
{
  "error": "Esta Idempotency-Key ya se usó con un payload distinto. Use una clave nueva."
}
Errores HTTP de la API Verifactu
HTTPCausaQué 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 formadaLeer error y corregir la llamada
401API key ausente o no válidaRevisar el header Authorization
403NIF desactivadoActivarlo en el panel o con la API de gestión de NIFs
400Datos no válidos (codigo vf-verifactu-…)Corregir y reenviar con una Idempotency-Key nueva
409Otra petición con la misma Idempotency-Key en cursoEsperar unos segundos y repetir
422Idempotency-Key reutilizada con otro cuerpoUsar una clave nueva
429Demasiadas peticiones con la misma API keyEsperar y reintentar con menos frecuencia
5xxError de servidorReintentar 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_total cuadra con las líneas y que, en el entorno de test, fecha_expedicion es 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.

Entorno de test y NIF de prueba incluidos

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?

El 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?

Sí. La AEAT la ha registrado, pero hay que corregir los errores con una subsanación o una rectificativa.

¿Dónde está la lista de códigos de error?

Los de validación de la API, en el catálogo de códigos de error de validación. Los de la AEAT, en su documento de validaciones y errores.

¿Cómo reintento sin duplicar una factura?

Con el header Idempotency-Key: la misma clave y el mismo cuerpo devuelven la primera respuesta sin crear otro registro.

¿Los códigos vf-verifactu pueden cambiar?

No cambian de significado. Pueden aparecer códigos nuevos: deja siempre una rama por defecto que use el campo error.

Prueba los errores en el entorno de test

Con la cuenta gratuita ves los errores antes de que lleguen a producción.

Entorno de test y NIF de prueba incluidosLee la documentación