country_unknown

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

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

• country_unsupported: country not supported for live validation
• invalid_format: VAT number format does not match the country
• not_found: generic resource-not-found