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
| Kind | When | Where you see it | What to do |
|---|---|---|---|
| Request error | The API does not accept the call (API key, NIF deactivated, representation form, idempotency) | HTTP 400 without codigo, 401, 403, 409 or 422 | Fix the call and repeat |
| API validation error | The invoice data are not valid | HTTP 400 with error and codigo (vf-verifactu-…) | Fix the data; no record was created |
| AEAT error | The AEAT processes the record and finds a problem | estado, codigo_error and mensaje_error in GET /verifactu/status or the webhook | Correct, 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.
{
"error": "El campo tipo_factura debe ser F1, F2, R1, R2, R3, R4, R5 o F3.",
"codigo": "vf-verifactu-tipo_factura_valor"
}| Code | Message (Spanish, as returned) |
|---|---|
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. |
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).
| State | What it means | What to do |
|---|---|---|
Pendiente | Queued, not yet sent to the AEAT | Wait (usually one or two minutes) or get it by webhook |
Correcto | Registered by the AEAT | Nothing |
Aceptado con errores | Registered by the AEAT, with errors | Correction with PUT /verifactu/modify or a corrective invoice |
Incorrecto | Rejected by the AEAT: the record is not on file | PUT /verifactu/modify with rechazo_previo X if the registration was rejected, or S if a correction was rejected |
Duplicado | A record with the same serie, numero and fecha_expedicion already exists | Check your numbering |
Anulado | Cancellation registered | Nothing |
Factura inexistente | The AEAT rejected the cancellation (for example, because the invoice is not on file) | Check the data or cancel without a previous record |
No registrado | The AEAT rejected the whole submission | Check the error, fix and send again |
Error servidor AEAT | Error at the AEAT | Nothing: 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 withPUT /verifactu/modifyor 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 withrechazo_previo(Xif the registration was rejected;Sif a correction was rejected).Duplicado: a record with the sameserie,numeroandfecha_expedicionalready 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 AEATneeds no retry from you: Verifacti resends the record.- The
Idempotency-Keyis kept for 24 hours: after that, before retrying check withPOST /verifactu/status(serie,numeroandfecha_expedicion) whether the invoice was registered.
{
"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 | Cause | What to do |
|---|---|---|
| 400 (no codigo) | Request rejected before validating the invoice: in production, representation form not signed; another treasury's endpoint; malformed Idempotency-Key | Read error and fix the call |
| 401 | Missing or invalid API key | Check the Authorization header |
| 403 | NIF deactivated | Activate it in the dashboard or with the NIF management API |
| 400 | Invalid data (codigo vf-verifactu-…) | Fix and send again with a new Idempotency-Key |
| 409 | Another request with the same Idempotency-Key in progress | Wait a few seconds and repeat |
| 422 | Idempotency-Key reused with a different body | Use a new key |
| 429 | Too many requests with the same API key | Wait and retry less often |
| 5xx | Server error | Retry 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_totalmatches the lines and that, in the test environment,fecha_expedicionis 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.
Other Verifactu tutorials
Questions about Verifactu errors
More questions about the Verifactu APIWhat is the difference between an API 400 and an AEAT error?
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?
Where is the list of error codes?
How do I retry without duplicating an invoice?
Idempotency-Key header: the same key and the same body return the first response without creating another record.Can the vf-verifactu codes change?
error field.Try the errors in the test environment
With the free account you see the errors before they reach production.