ALTERNATIVE_ID_COUNTRY

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.

Category: Customers


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

When it happens

An alternative_id has no country_code, and its type needs one. Only PASSPORT and NOT_REGISTERED can omit it: without it they are taken as Spanish (ES). error.details names the field where it was sent: alternative_id.country_code on a customer, recipient.alternative_id.country_code on an invoice recipient.

How to fix it

Send country_code inside alternative_id: the ISO 3166-1 alpha-2 code of the country that issued the document, such as DE for a German VAT number. It is not taken from the address.

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_COUNTRY_REQUIRED",
  "title": "ALTERNATIVE_ID_COUNTRY_REQUIRED",
  "detail": "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.",
  "instance": "/v1/<resource>",
  "errors": [],
  "success": false,
  "error": {
    "code": "ALTERNATIVE_ID_COUNTRY_REQUIRED",
    "message": "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.",
    "details": {}
  },
  "meta": {
    "timestamp": "2026-05-21T10:00:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

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

Message

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.

Falta el país del identificador alternativo (alternative_id.country_code). Es obligatorio salvo para los tipos PASSPORT y NOT_REGISTERED, que sin país se toman como de España.

Falta el país del document identificatiu alternatiu (alternative_id.country_code). És obligatori llevat dels tipus PASSPORT i NOT_REGISTERED, que sense país es prenen com a espanyols.

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

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_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

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

ALTERNATIVE_ID_COUNTRY_REQUIRED