ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY

An EU VAT number (NIF_IVA, type 02) is only valid for an EU member state other than Spain; received country: '‹value›'. Identify a customer from outside the EU with another type, such as OTHER_DOCUMENT or COUNTRY_ID. If it is the recipient of an invoice already issued, correct its data with an R4 corrective invoice

Category: Customers


HTTP status	`422` Unprocessable Content
Retry	After fixing the cause

When it happens

An alternative_id of type NIF_IVA carries a country_code that is not an EU Member State other than Spain. AEAT accepts an EU VAT number only from another Member State.

How to fix it

Identify a customer from outside the EU with another type, such as OTHER_DOCUMENT or COUNTRY_ID. A Spanish customer goes in nif. A customer saved before this rule keeps its identifier and can be read, but an invoice to it is not issued until you change the identifier.

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.

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_REQUIRES_EU_COUNTRY",
  "title": "ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY",
  "detail": "An EU VAT number (NIF_IVA, type 02) is only valid for an EU member state other than Spain; received country: '‹value›'. Identify a customer from outside the EU with another type, such as OTHER_DOCUMENT or COUNTRY_ID. 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_REQUIRES_EU_COUNTRY",
    "message": "An EU VAT number (NIF_IVA, type 02) is only valid for an EU member state other than Spain; received country: '‹value›'. Identify a customer from outside the EU with another type, such as OTHER_DOCUMENT or COUNTRY_ID. 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

Un NIF-IVA (NIF_IVA, tipo 02) solo es válido para un Estado miembro de la UE distinto de España; país recibido: '‹value›'. Identifica a un cliente de fuera de la UE con otro tipo, como OTHER_DOCUMENT o COUNTRY_ID. Si es el destinatario de una factura ya expedida, rectifica sus datos con una R4

Un NIF-IVA (NIF_IVA, tipus 02) només és vàlid per a un Estat membre de la UE diferent d'Espanya; país rebut: '‹value›'. Identifica un client de fora de la UE amb un altre tipus, com OTHER_DOCUMENT o COUNTRY_ID. Si és el destinatari d'una factura ja expedida, rectifica'n les dades amb una R4

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

ALTERNATIVE_ID_AND_NIF_EXCLUSIVE

The customer cannot carry both a NIF and an alternative identifier. Use only one

ALTERNATIVE_ID_COUNTRY_REQUIRED

The country of the alternative identifier is missing (alternative_id.country_code). It is required except for the PASSPORT and NOT_REGISTERED types, which are taken as Spanish when it is omitted.

ALTERNATIVE_ID_INVALID

The alternative identifier is not valid

ALTERNATIVE_ID_REQUIRES_SPAIN

Type NOT_REGISTERED (07) is only valid for Spain; received country: '‹value›'

ALTERNATIVE_ID_SPAIN_INVALID_TYPE

For customers with country ES only types PASSPORT (03) or NOT_REGISTERED (07) are allowed

Keep exploring

All Customers errors

Every code in this category in one table.

Error reference home

Browse every category or jump to the handling guide.

ALTERNATIVE_ID_VAT_INVALID_FORMAT

'‹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

API_COMMUNICATION_ERROR

Error communicating with the VeriFactu API