Verifactu errors: what they mean and how to fix them

When you send an invoice to Verifactu with the Verifactu API you can get three kinds of error: request errors (HTTP 400 without codigo, 401, 403, 409 or 422), Verifacti's prior validation (HTTP 400 with a stable vf-verifactu-… code; the invoice never reaches the AEAT) and the error the AEAT returns when it processes the record, which you see in the state (Aceptado con errores, Incorrecto…) with its codigo_error and mensaje_error.

The three kinds of error

Kinds of error when sending invoices with the Verifactu API
KindWhenWhere you see itWhat to do
Request errorThe API does not accept the call (API key, NIF deactivated, representation form, idempotency)HTTP 400 without codigo, 401, 403, 409 or 422Fix the call and repeat
API validation errorThe invoice data are not validHTTP 400 with error and codigo (vf-verifactu-…)Fix the data; no record was created
AEAT errorThe AEAT processes the record and finds a problemestado, codigo_error and mensaje_error in GET /verifactu/status or the webhookCorrect, issue a corrective invoice or review, depending on the state

API validation errors

Before sending anything to the AEAT, the API validates the invoice data against its rules. If something is not valid, it answers 400 with a description in Spanish (error) and a stable code (codigo), and no record is created. Code against codigo (its meaning never changes) and keep a default branch that shows error: the catalogue grows when rules are added.

Response · 400
{
  "error": "El campo tipo_factura debe ser F1, F2, R1, R2, R3, R4, R5 o F3.",
  "codigo": "vf-verifactu-tipo_factura_valor"
}
Common Verifactu API validation errors
CodeMessage (Spanish, as returned)
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.

The full catalogue of the Verifactu API (155 codes as of 18 November 2026) is in codigos-verifactu.yaml.

Record states

GET /verifactu/status?uuid=… and the webhooks give the state of the invoicing record (not necessarily of the invoice: one invoice can have several records).

States of an invoicing record in the Verifactu API
StateWhat it meansWhat to do
PendienteQueued, not yet sent to the AEATWait (usually one or two minutes) or get it by webhook
CorrectoRegistered by the AEATNothing
Aceptado con erroresRegistered by the AEAT, with errorsCorrection with PUT /verifactu/modify or a corrective invoice
IncorrectoRejected by the AEAT: the record is not on filePUT /verifactu/modify with rechazo_previo X if the registration was rejected, or S if a correction was rejected
DuplicadoA record with the same serie, numero and fecha_expedicion already existsCheck your numbering
AnuladoCancellation registeredNothing
Factura inexistenteThe AEAT rejected the cancellation (for example, because the invoice is not on file)Check the data or cancel without a previous record
No registradoThe AEAT rejected the whole submissionCheck the error, fix and send again
Error servidor AEATError at the AEATNothing: Verifacti resends the record

Errors returned by the AEAT

When the AEAT finds a problem, GET /verifactu/status and the webhook include codigo_error and mensaje_error exactly as the AEAT returns them. Each code, with the validation behind it, is in the AEAT validations and errors document (v1.2.2), which also separates errors that reject the record from those that accept it with errors. The code list is on the validations and errors page of the developer portal.

Invoice accepted with errors: what to do

  • Aceptado con errores: the AEAT registered the invoice but found errors. Send a correction with PUT /verifactu/modify or issue a corrective invoice, depending on whether the error is in the record or in the invoice.
  • Incorrecto: the invoice is not on file at the AEAT. Send the correction with rechazo_previo (X if the registration was rejected; S if a correction was rejected).
  • Duplicado: a record with the same serie, numero and fecha_expedicion already exists. Check your numbering before sending again.

Retry without duplicates

Use the Idempotency-Key header on /create, /create_bulk, /modify and /cancel, with the same key on every retry of an invoice. How to do it in your language, in the tutorials by language.

  • A retry with the same key and the same body returns the first response, with Idempotent-Replayed: true, and creates no new record.
  • Error servidor AEAT needs no retry from you: Verifacti resends the record.
  • The Idempotency-Key is kept for 24 hours: after that, before retrying check with POST /verifactu/status (serie, numero and fecha_expedicion) whether the invoice was registered.
Response · 409
{
  "error": "idempotent_request_in_progress",
  "message": "Otra petición con esta Idempotency-Key se está procesando. Reintente en unos segundos."
}
Response · 422
{
  "error": "Esta Idempotency-Key ya se usó con un payload distinto. Use una clave nueva."
}
Verifactu API HTTP errors
HTTPCauseWhat to do
400 (no codigo)Request rejected before validating the invoice: in production, representation form not signed; another treasury's endpoint; malformed Idempotency-KeyRead error and fix the call
401Missing or invalid API keyCheck the Authorization header
403NIF deactivatedActivate it in the dashboard or with the NIF management API
400Invalid data (codigo vf-verifactu-…)Fix and send again with a new Idempotency-Key
409Another request with the same Idempotency-Key in progressWait a few seconds and repeat
422Idempotency-Key reused with a different bodyUse a new key
429Too many requests with the same API keyWait and retry less often
5xxServer errorRetry with the same Idempotency-Key

How to prevent errors

  • Test each invoice type in the test environment before going to production, starting from the Verifactu examples.
  • Let the API check the recipient's NIF against the AEAT census (it does by default; in the test environment you can turn it off with validar_destinatario: false, in production it is always checked), or try it first with the NIF checker.
  • Check that importe_total matches the lines and that, in the test environment, fecha_expedicion is today's date.
  • If you generate the XML yourself, run it through the Verifactu XML validator or validate it against the XSD (how).

Next step

The Verifactu API validates the data before sending them to the AEAT and returns each validation error with a stable code. Start with the quick start guide or the documentation.

Test environment and test NIF included

Questions about Verifactu errors

More questions about the Verifactu API

What is the difference between an API 400 and an AEAT error?

Verifacti returns the 400 before sending anything: no record is created. The AEAT error comes later, in the record state, with codigo_error and mensaje_error.

Is an invoice in «Aceptado con errores» registered?

Yes. The AEAT registered it, but the errors have to be fixed with a correction or a corrective invoice.

Where is the list of error codes?

The API validation codes, in the validation error code catalogue. The AEAT ones, in its validations and errors document.

How do I retry without duplicating an invoice?

With the Idempotency-Key header: the same key and the same body return the first response without creating another record.

Can the vf-verifactu codes change?

Their meaning never changes. New codes can appear: always keep a default branch that uses the error field.

Try the errors in the test environment

With the free account you see the errors before they reach production.

Test environment and test NIF includedRead the documentation