# 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.

<Callout type="info">
**Category:** [Customers](/errors/category/cliente)
</Callout>

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

- [`POST /v1/companies/{company_id}/customers`](/customers/createCompanyCustomer)
- [`PATCH /v1/companies/{company_id}/customers/{customer_id}`](/customers/patchCompanyCustomer)
- [`POST /v1/companies/{company_id}/invoices`](/invoices/createCompanyInvoice)
- [`POST /v1/companies/{company_id}/recurring-invoices`](/recurring-invoices/createCompanyRecurringInvoice)

## Rules that cite this code

- [CNT-021 · A recipient without a Spanish NIF is identified by an alternative id](/rules/contents#cnt-021)

## Example response

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

```json
{
  "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

<Tabs items={["English", "Spanish", "Catalan"]}>
  <Tab value="English">{"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."}</Tab>
  <Tab value="Spanish">{"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."}</Tab>
  <Tab value="Catalan">{"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."}</Tab>
</Tabs>

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

## Other errors in this category

<div className="grid grid-cols-2 gap-3 not-prose">
  <Card title="ALTERNATIVE_ID_AND_NIF_EXCLUSIVE" description="The customer cannot carry both a NIF and an alternative identifier. Use only one" href="/errors/ALTERNATIVE_ID_AND_NIF_EXCLUSIVE" />
  <Card title="ALTERNATIVE_ID_INVALID" description="The alternative identifier is not valid" href="/errors/ALTERNATIVE_ID_INVALID" />
  <Card title="ALTERNATIVE_ID_REQUIRES_SPAIN" description="Type NOT_REGISTERED (07) is only valid for Spain; received country: '‹value›'" href="/errors/ALTERNATIVE_ID_REQUIRES_SPAIN" />
  <Card title="ALTERNATIVE_ID_SPAIN_INVALID_TYPE" description="For customers with country ES only types PASSPORT (03) or NOT_REGISTERED (07) are allowed" href="/errors/ALTERNATIVE_ID_SPAIN_INVALID_TYPE" />
  <Card title="ALTERNATIVE_ID_VAT_INVALID_FORMAT" description="'‹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" href="/errors/ALTERNATIVE_ID_VAT_INVALID_FORMAT" />
</div>

## Keep exploring

<div className="grid grid-cols-2 gap-3 not-prose">
  <Card title="All Customers errors" description="Every code in this category in one table." href="/errors/category/cliente" />
  <Card title="Error reference home" description="Browse every category or jump to the handling guide." href="/errors" />
</div>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi