vatverify home
Start free
All errors

country_unknown

The country code passed to the rates endpoint does not exist in the dataset.

HTTP 404 · Not Found

Example response

{
  "error": {
    "code": "country_unknown",
    "message": "Country code 'xx' not found in rates dataset."
  },
  "meta": {
    "request_id": "a1b2c3d4-...",
    "latency_ms": 0
  }
}

What happened

You called GET /v1/rates/:country with a country code that does not exist in the VAT rates dataset. Unlike country_unsupported (which is about live validation), this error is specific to the rates endpoints.

How to fix

  1. Call GET /v1/rates (no country code) to get the full list of valid country codes.
  2. Country codes in the rates endpoint are lowercase: use de, not DE.
  3. For Greece, use el not gr.

Country code conventions

The rates dataset uses ISO 3166-1 alpha-2 codes in lowercase, with two intentional deviations that match the EU VAT system:

  • el for Greece (not gr). The EU VAT prefix uses EL derived from "Hellas".
  • xi for Northern Ireland (not part of ISO 3166). The XI prefix was created post-Brexit for Northern Ireland goods trade with the EU.

Both deviations also apply when validating VAT numbers through /v1/validate. See the VAT number glossary for the full list of country code conventions.

Common scenarios that hit this error

  • Pulling rates from a hardcoded country list that includes non-EU codes. Calling /v1/rates/us or /v1/rates/jp will return country_unknown because the rates dataset is scoped to the 32 supported countries (EU-27 plus XI, GB, CH, LI, NO).
  • Uppercase codes: GET /v1/rates/DE is rejected; the canonical form is lowercase.
  • Country codes that exist on the validation side but not in rates: in current versions of the API, all 32 validation-supported countries also have rates, so this divergence does not occur. If new validation-only or rates-only countries are added in future, this error is what surfaces the gap.

Common mistakes

  • Uppercase country codes: GET /v1/rates/DE will fail; use /v1/rates/de.
  • Using gr for Greece: the correct code in the rates dataset is el.
  • Confusing this with country_unsupported: country_unknown only comes from the rates endpoints, not from validation.

Related errors