Handling AEAT rejections

A registered invoice is immutable, so a rejection is resolved with a new fiscal document or, when the cause lies outside the invoice, by contacting BeeL. This page tells you which, from what the invoice says.

For the full state machine, see Submission states. For choosing between a corrective and a void, see Cancel vs amend.

Read the invoice first

Three fields on the invoice's verifactu block tell you where you are: submission_status, error_code and error_message.

To see each record separately — the registration and, if you voided, the cancellation — use List the VeriFactu records of an invoice. Each record carries its own submission_status and, read the same way as on the invoice, its own error_message and error_code.

A temporary AEAT error stays PENDING

When AEAT answers with a temporary server-side error, the invoice is not rejected: it stays PENDING, with no error_code or error_message, while BeeL. retries it, and no verifactu.status.updated is sent. It moves to ACCEPTED or REJECTED when AEAT gives a real answer, or to REJECTED if the retries run out:

PENDING  →  (AEAT server-side error; BeeL. retries, still PENDING)  →  ACCEPTED or REJECTED

So a REJECTED invoice does not move on its own: it is safe to act on it.

Accepted with errors

ACCEPTED with an error_code means AEAT registered the invoice but reported a problem with some of its data. The invoice is valid and in AEAT's registry; you do not need to resubmit it, and it will not change on its own.

A typical cause is the recipient: AEAT could not match the recipient's NIF and name against its census. That can happen when the customer's NIF could not be checked against the census at the time the customer was saved — BeeL. lets the customer through rather than block you, and AEAT flags it later.

What to do:

1. Read error_message to see what AEAT flagged.
2. Check that data — usually the recipient's NIF and legal name — against the customer's real details.
3. If it was right, nothing else is needed. If it was wrong, fix it in the customer's data so the following invoices carry it right. A corrective does not change it on the invoice already recorded: it keeps the recipient of the invoice it corrects (COR-017 A corrective keeps the recipient, except to correct the recipient's data). See REC-009 Check the data AEAT accepted with errors.

AEAT codes by what to do

error_code carries AEAT's code unchanged. These are the codes you are most likely to meet, grouped by who has to act. AEAT has many more; the complete list is in the AEAT VeriFactu documentation.

Recipient data — fix the invoice

What to do: check the recipient against the census with the NIF validation API and fix the customer record. A corrective is not the way: the rejected invoice is not in AEAT's registry, and correcting it answers CORRECTIVE_ORIGINAL_RECORD_REJECTED. Void it — that sends nothing to AEAT; if it was already sent or paid, the void needs issued_in_error: true — and issue a new invoice with the corrected recipient.

The issuer's own setup — fix the NIF, then contact support

What to do: the invoice's data is fine; the taxpayer's situation with AEAT is not. Resolve it — register the NIF with AEAT, or sign the representation — and then contact BeeL. with the invoice. Nothing in the invoice needs correcting, so do not issue a corrective for these.

Suspended access — the taxpayer must talk to AEAT

What to do: only AEAT can lift it. The taxpayer must contact AEAT; once it is lifted, contact BeeL. with the affected invoices.

Records — usually nothing to fix in the data

Invoice content — fix the invoice

What to do: issue a corrective with the right data. BeeL. validates most of these before submitting, so they are rare; if you cannot see what is wrong, contact support with the invoice ID.

Record format — contact support

What to do: these point at how the record was built, not at your data. Contact support with the invoice ID.

Temporary AEAT errors — wait

What to do: nothing. While BeeL. retries, the invoice stays PENDING and these codes are not published on it. If the retries run out, the invoice becomes REJECTED without an AEAT verdict: contact support.

Reconcile, do not only listen

verifactu.status.updated tells you each time the public status of a record changes, including a submission refused before it reached AEAT or one BeeL. stopped waiting for; NOT_SUBMITTED never produces one, because there is no record to change. Treat the webhook as the fast path and a periodic sweep as the safety net:

# Invoices AEAT does not have
curl "https://app.beel.es/api/v1/companies/{company_id}/invoices?verifactu_status=REJECTED" \
  -H "Authorization: Bearer $BEEL_API_KEY"

# Invoices that should have gone to AEAT and have no record
curl "https://app.beel.es/api/v1/companies/{company_id}/invoices?verifactu_status=NOT_SUBMITTED" \
  -H "Authorization: Bearer $BEEL_API_KEY"

Run it on a schedule (daily is plenty for most volumes), compare with what you already know, and handle anything new as above. There is no need to sweep ACCEPTED invoices: an accepted record never turns into a rejected one — see Is ACCEPTED final?. Keep the job within your rate limits.

NOT_SUBMITTED right after issuing is normal while the submission is in flight; only act on invoices that stay there.

The number is already taken at AEAT

AEAT identifies an invoice by the issuer's NIF, its number and its issue date. If it already holds a record with this invoice's number and date that is not this invoice — typically one issued with the software you used before, under the same NIF — BeeL. does not take that record as this invoice's. The invoice ends REJECTED, with no error_code and an error_message that says the number is taken, and it is not registered. Retrying does not help: it meets the same record. See NUM-002 An issued number is never reused, even when the invoice is voided.

What to do: issue the invoice again with a number AEAT does not hold yet, from another series or a series that continues the sequence of your previous software. The rejected invoice is not in AEAT's registry, so voiding it sends nothing to AEAT — see Cancel vs amend.

Fixing the invoice

When the rejection is about the invoice's data, the fix is always a new fiscal document: a corrective or, for an invoice that should never have been issued, a void. A registered invoice is never edited. Which one fits each situation, including an invoice AEAT never registered, is in the decision matrix of Cancel vs amend.

When to contact support

Write to it@beel.es with the invoice ID(s) and the error_code / error_message you see when:

• the invoice is REJECTED with no error_code — the record never reached AEAT, or BeeL. gave up waiting — unless error_message says the number is already taken;
• the invoice stays NOT_SUBMITTED;
• the cause was outside the invoice (issuer not in the census, representation not signed, suspended access) and you have fixed it;
• the code is a duplicate (3000), a record-format code, or you cannot tell what is wrong.

When a registration that never reached AEAT — one refused before it got there, or one BeeL. stopped waiting for — is sent again, the new attempt replaces the undelivered one. The invoice keeps its number. In its VeriFactu records, a registration refused before reaching AEAT is listed as REJECTED until the invoice is sent again; the new attempt then takes its place, since the undelivered one was never a record at AEAT.

Related