Error codes

Every error response has the same shape. Branch on error.code, not on the message, which may change.

{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Monthly limit of 1,000 requests exceeded. …",
    "doc_url": "https://www.taxid.dev/docs/errors#rate_limit_exceeded"
  }
}

missing_authorization

HTTP 401 · type authentication · No API key sent

What it means: The request had no Authorization: Bearer <key> header, or the header was empty.
How to fix it: Send your key as Authorization: Bearer vat_…. Keys are created in the dashboard under API keys.
Retry?: No — fix the request

invalid_api_key

HTTP 401 · type authentication · API key not valid

What it means: The key does not exist or has been revoked.
How to fix it: Check for a typo or stray whitespace, or create a new key in the dashboard. Revoked keys never come back.
Retry?: No — fix the request

rate_limit_exceeded

HTTP 429 · type rate_limit · Quota used up

What it means: Your plan's monthly validations are spent (or, on the free web checker, the hourly per-IP limit). X-RateLimit-Reset says when it resets, as a Unix timestamp.
How to fix it: Wait for the reset or upgrade your plan in the dashboard. Do not retry in a loop: every attempt is refused until the reset.
Retry?: After the reset

invalid_country

HTTP 400 · type invalid_request · No data for that country code

What it means: Returned by GET /api/v1/rates/{country} when there is no VAT/GST rate data for the code.
How to fix it: Use a two-letter country code from GET /api/v1/rates, which lists every supported country.
Retry?: No — fix the request

country_not_supported

HTTP 400 · type invalid_request · Country not supported

What it means: TaxID cannot validate tax IDs for that country code (or the code does not exist).
How to fix it: Use a two-letter country code TaxID supports, such as DE, ES or FR. The full list is in the API reference.
Retry?: No — fix the request

invalid_vat_format

HTTP 400 · type invalid_request · Number has the wrong format

What it means: Reserved. Today a number with the wrong format is answered with HTTP 200 and "status": "invalid", not with this error.
How to fix it: Handle it like status: invalid: check the length and characters of the number for that country.
Retry?: No — fix the request

invalid_request_body

HTTP 400 · type invalid_request · Malformed request

What it means: The JSON body is missing, not valid JSON, or does not have the expected fields.
How to fix it: Compare the body with the schema in /openapi.json.
Retry?: No — fix the request

batch_too_large

HTTP 400 · type invalid_request · Batch too large

What it means: A batch request had more numbers than one call accepts.
How to fix it: Split the list into smaller batches.
Retry?: No — fix the request

service_unavailable

HTTP 503 · type service_unavailable · Registry unavailable

What it means: VIES or the national tax authority did not answer in time, or TaxID's daily allowance of live VIES lookups is spent. It says nothing about the number itself.
How to fix it: Do not treat the number as invalid. Accept the customer provisionally and retry later; cached results keep working during outages.
Retry?: Yes, with backoff

internal_server_error

HTTP 500 · type api_error · Unexpected error

What it means: Something failed on TaxID's side. It has been reported to the team automatically.
How to fix it: Retry with exponential backoff. If it persists, write to support@taxid.dev with the time of the request.
Retry?: Yes, with backoff

API Reference / Errors