VeriFactu error codes
Every public API error code emitted by VeriFactu, with its HTTP status, its type and a page per code.
Error codes emitted by VeriFactu. Each code links to its own page with the cause and the action to take.
| Code | Type | HTTP | Description |
|---|---|---|---|
alta_record_not_found | not_found_error | 404 | The invoice has no registration record, so the operation that depends on it has nothing to work with. |
anulacion_record_already_exists | conflict_error | 409 | The invoice already carries an annulment record in the chain, and annulment is reported only once. |
certificate_expired | invalid_request_error | 422 | The certificate is outside its validity window: it has expired, or it is not valid yet. |
certificate_nif_mismatch | invalid_request_error | 422 | The tax id of the certificate holder does not match the company tax id. AEAT records are signed on behalf of the company, so both must be the same. |
certificate_not_found | not_found_error | 404 | The company has no FNMT certificate matching the identifier, or none uploaded at all. |
certificate_too_large | invalid_request_error | 422 | The file exceeds the 100 KB limit, while a real FNMT certificate weighs a few kilobytes. |
chain_position_conflict | conflict_error | 409 | Two records of the same company tried to take the same position in the fingerprint chain at the same time, and the automatic retries could not resolve the collision. |
clock_drift_exceeded | invalid_request_error | 422 | The server clock drifted from NTP beyond the allowed margin. The generation timestamp is part of the AEAT fingerprint, so an unsynchronised clock would produce records AEAT rejects. |
declaracion_already_exists | conflict_error | 409 | The company already filed its SIF responsibility statement for that period. |
declaracion_not_found | not_found_error | 404 | The company has no SIF responsibility statement filed for the requested period. |
event_already_processed | invalid_request_error | 422 | That SIF event is already recorded in the event chain, and each event is processed exactly once. |
invalid_certificate_format | invalid_request_error | 422 | The file is not a PKCS#12 container: its first bytes do not match the ASN.1 structure the format requires, whatever its extension says. |
invalid_certificate_password | invalid_request_error | 422 | The password does not open the certificate file. |
invalid_representation | invalid_request_error | 422 | The representation breaks a rule: the signed Annex I or the power-of-attorney evidence is missing, the document is not a valid PDF or exceeds 5 MB, signer_name, power_of_attorney_reference or the revocation reason (reason, 3 to 500 characters) do not respect their length, valid_until is earlier than granted_on or more than 5 years after it, or the representation is already revoked (or there is no current one to revoke). |
max_retries_exceeded | invalid_request_error | 422 | It only applies to the EVENTS of the NO VERI*FACTU mode (POST /v1/companies/{company}/verifactu/events/{id}/retry): the event exhausted its transmission attempts. Billing records have NO retry limit — art. 16.4 of Order HAC/1177/2024 requires retrying at least once an hour while the incident lasts — so no record retry returns this code any more. |
mode_switch_blocked_until_year_end | invalid_request_error | 422 | VeriFactu mode was activated during this fiscal year and at least one billing record was issued. Stepping back would degrade the integrity of a chain already reported to AEAT. |
record_already_accepted | invalid_request_error | 422 | AEAT already accepted the record. Acceptance is terminal and its content is frozen as part of the fingerprint chain. |
record_immutable | invalid_request_error | 422 | The record belongs to an append-only ledger: once written, its fiscal content is closed to changes and to deletion. |
record_not_rejected | invalid_request_error | 422 | Only an alta record that AEAT accepted (or accepted with errors) or rejected can be subsanado. This record is in another state — pending remission, submitted with no answer yet or in technical error — which the retry covers, not the subsanación. |
record_not_subsanable | invalid_request_error | 422 | The record cannot be subsanado: it is not a registration (alta) record, it is not the LAST alta of its invoice (a later subsanación replaces it), the invoice is annulled, it is a rejected record whose corrected alta is already waiting to be resent, or it has no source invoice from which its data could be regenerated. |
representation_required | invalid_request_error | 422 | The remission mode asks Factuarea to submit your records to AEAT on your behalf, and the company has no current representation — neither revoked nor expired — of the kind that mode needs (the signed Annex I for social_collaborator, the registered power of attorney for power_of_attorney). |
requires_annulment | invalid_request_error | 422 | The regenerated content changes a field that takes part in the fingerprint — issuer tax id, series and number, issue date, invoice type, tax amount or total — and the chain cannot be rewritten. |
signing_certificate_unavailable | invalid_request_error | 422 | The company has VeriFactu enabled in NO VERI*FACTU mode, where every billing record is signed (Order HAC/1177/2024, arts. 6.c and 14), and there is nothing to sign it with. error.param says WHAT is missing, and it is stable: certificate = the company certificate is missing, expired or revoked, carries another company's tax id, or its .p12 file cannot be read (damaged, or the stored password is no longer valid); representation = in the third-party remission modes, the representation that lets Factuarea sign on the company's behalf is not active; system_certificate = the Factuarea certificate is unavailable or cannot be read. Without a signature there is no valid record, and an issued or annulled invoice cannot be left without its own, so the operation is rejected before it runs. |
sii_excluded | invalid_request_error | 422 | The company is registered with SII, and SII filers are excluded from the VeriFactu regulation. |
social_collaborator_unavailable | invalid_request_error | 422 | The social collaboration agreement with AEAT is not yet in force on this instance, so the social_collaborator mode cannot be selected. |
system_certificate_unavailable | api_error | 500 | The Factuarea certificate that submits records in the third-party modes is missing, expired or revoked. It is a problem on our side, not in your request. |
verifactu_already_submitted | invalid_request_error | 422 | The invoice already has its registration record. Exactly one registration exists per invoice, so a second one would break the idempotency of the chain. |
verifactu_mode_invalid | invalid_request_error | 422 | The mode is outside the catalogue verifactu / no_verifactu. |
verifactu_not_eligible | invalid_request_error | 422 | The invoice cannot be registered with AEAT right now: the company is not on VeriFactu mode, it has no active certificate, or the certificate is revoked or issued for a different tax id. When issuing or annulling, the same code with the subcode signing_certificate_unavailable means the company, with VeriFactu enabled in NO VERI*FACTU mode, has nothing to sign the record with (error.param: certificate, representation or system_certificate, depending on what is missing), and with other error.param values that a field of the invoice does not fit the alta record (read error.param and error.message). |
verifactu_record_not_found | not_found_error | 404 | The identifier does not match any billing record of the authenticated company. |
verifactu_transmission_failed | invalid_request_error | 422 | The transmission of the record to AEAT did not complete: the endpoint was unreachable or answered with an incident. |
Related
Error codes by category
Find an error by the category that emits it.
Full reference table
All codes, HTTP statuses, types and descriptions in one reference.
Error model
Interpret the error envelope and handle errors by code.