ALTERNATIVE_ID_VAT_INVALID_FORMAT

When it happens

An alternative_id of type NIF_IVA has a number without the EU VAT structure AEAT defines for its country: the country prefix (EL for Greece) followed by the national number, without spaces.

How to fix it

Send the full EU VAT number with its prefix, e.g. FR40303265045 for France or EL094014201 for Greece, and make country_code the country of that prefix. Lowercase letters are accepted and stored in uppercase. A well-formed number can still be refused after the invoice is issued if it is not in the VIES census: check it there first.

Retry

Not as is: the same request fails the same way. Fix the cause described above, then send the request again, under a new Idempotency-Key if the body changed.

Returned by

The operations where this code is most likely. The list is not exhaustive.

• POST /v1/companies/{company_id}/customers
• PATCH /v1/companies/{company_id}/customers/{customer_id}
• POST /v1/companies/{company_id}/invoices
• POST /v1/companies/{company_id}/invoices/{invoice_id}/issue
• POST /v1/companies/{company_id}/recurring-invoices

Rules that cite this code

• CNT-021 A recipient without a Spanish NIF is identified by an alternative id

Example response

When this error occurs, the API answers 422 Unprocessable Content with a JSON body of this shape:

{
  "type": "https://docs.beel.es/errors/ALTERNATIVE_ID_VAT_INVALID_FORMAT",
  "title": "ALTERNATIVE_ID_VAT_INVALID_FORMAT",
  "detail": "'‹value›' is not a valid EU VAT number for that country: it must be the prefix '‹value›' followed by the country's VAT number, in capital letters and without spaces. If it is the recipient of an invoice already issued, correct its data with an R4 corrective invoice",
  "instance": "/v1/<resource>",
  "errors": [],
  "success": false,
  "error": {
    "code": "ALTERNATIVE_ID_VAT_INVALID_FORMAT",
    "message": "'‹value›' is not a valid EU VAT number for that country: it must be the prefix '‹value›' followed by the country's VAT number, in capital letters and without spaces. If it is the recipient of an invoice already issued, correct its data with an R4 corrective invoice",
    "details": {}
  },
  "meta": {
    "timestamp": "2026-05-21T10:00:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

The type URI is stable and always resolves to this page.

Message

Send the request with Accept-Language: <es|en|ca> to receive the message in your preferred language.

Placeholders like ‹value› are filled in at runtime with the actual values of your request.

Other errors in this category

Keep exploring