Response Format

Every Avatcado response follows the same envelope pattern: either data or error, always accompanied by meta. This means if (response.error) always works as a check.

Success response

{
  "data": {
    "valid": true,
    "vat_number": "NL123456789B01",
    "country_code": "NL",
    "company": {
      "name": "Acme B.V.",
      "address": "Keizersgracht 123, Amsterdam"
    },
    "requested_at": "2026-03-06T12:00:00Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "request_duration_ms": 120,
    "source": "vies",
    "source_status": "live",
    "cached": false,
    "stale": false
  }
}

`data` fields

Field	Type	Description
`valid`	`boolean`	Whether the VAT number is active and registered
`vat_number`	`string`	The normalized VAT number
`country_code`	`string`	Two-letter country code
`company`	`object \| null`	Company name and address. Null when the number is invalid or the registry publishes no company data (Germany and Spain via VIES). See per-country availability
`company.name`	`string`	Registered company name
`company.address`	`string \| null`	Registered address
`consultation_number`	`string`	VIES/HMRC consultation number. Only present when `requester_vat_number` is provided. Not available for CH, LI, NO, or AU validations, and never present on a national registry fallback response (`meta.source_status: "fallback"`, Pro and Business plans). A request with `requester_vat_number` therefore skips the register and the cache by default, so the number always comes from a fresh check; pass `cache=true` to accept a stored one
`requested_at`	`string`	ISO 8601 timestamp of the validation

Error response

{
  "error": {
    "code": "invalid_vat_format",
    "message": "The VAT number format is invalid. Expected format: CC123456789",
    "docs_url": "https://docs.avatcado.com/errors/invalid_vat_format",
    "vat_number": "DE123"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

`error` fields

Field	Type	Description
`code`	`string`	Machine-readable error code
`message`	`string`	Human-readable explanation
`docs_url`	`string`	Link to the error documentation page
`vat_number`	`string`	The normalized VAT number from the request, echoed back when one was submitted. Not present on authentication errors
`requester_vat_number`	`string`	The normalized requester VAT number from the request, echoed back when supplied
`details`	`array`	Field-level issues for `validation_error` responses: `[{ field, message }]`

`meta` fields

Present on every response, success or error.

Field	Type	Description
`request_id`	`string`	Unique request identifier (UUID)
`request_duration_ms`	`number`	Total request processing time in milliseconds (success responses only)
`source`	`string`	Registry that produced the served data: `"vies"`, `"hmrc"`, `"bfs"`, `"brreg"`, `"abr"`, a national registry id (`"anaf"`, `"ares"`, `"dgfip"`, `"fssr"`, `"furs"`, `"kbo"`, `"porezna"`, `"prh"`, `"rik"`, `"vid"`, see Supported Countries), or `"test"` in test mode. Always present on validation responses
`source_status`	`string`	How the result was obtained: `"live"` (fresh upstream lookup), `"cached"` (served from the 25-day cache), `"unavailable"` (upstream down, most recent cached result served, check `stale`), `"degraded"` (possible silent false negative, prior result served), or `"fallback"` (VIES down, the national registry in `source` confirmed the number; Pro and Business plans only). Always present on validation responses
`cached`	`boolean`	`true` when the result was served from a stored row. Always present on validation responses
`stale`	`boolean`	`true` when the served row is older than the 25-day TTL and was only served because the upstream failed. Always present on validation responses
`cached_at`	`string`	ISO 8601 timestamp of the served row. Present only when `cached` is `true`
`mode`	`string`	`"test"` when using a test key. Omitted for live keys
`validation_id`	`string`	Error responses only: identifier of the recorded failed validation attempt. Present on `upstream_unavailable` and `upstream_member_state_unavailable` errors

Batch items

Each item in a batch validation response uses the same envelope:

Success: { data: VatValidationData, meta }. The data object is the exact same shape as the single validate endpoint
Error: { error, meta }. The error object contains the normalized vat_number that failed (meta.vat_number is kept for backward compatibility but deprecated)

Per-item meta always contains source, source_status, cached and stale (plus cached_at when cached). Request-level fields like request_id and request_duration_ms live on the top-level meta.

Response headers

Header	When present	Description
`X-Request-Id`	Always	Unique request identifier matching `meta.request_id`
`X-RateLimit-Limit`	Authenticated requests	Total requests allowed this period
`X-RateLimit-Remaining`	Authenticated requests	Requests remaining this period
`X-RateLimit-Reset`	Authenticated requests	When the quota resets (ISO 8601)
`X-Burst-Limit`	Authenticated requests	Per-minute burst limit for your tier
`X-Burst-Remaining`	Authenticated requests	Burst requests remaining this minute
`Retry-After`	429 and 503 responses	Seconds to wait before retrying

Request ID header

Every response includes an X-Request-Id header matching meta.request_id. You can pass your own X-Request-Id header and it will be echoed back - useful for correlating requests in your own logging.

curl -H "Authorization: Bearer avat_live_your_api_key" \
  -H "X-Request-Id: my-trace-id-123" \
  "https://api.avatcado.com/v1/validate?vat_number=NL123456789B01"

const { data, error } = await avatcado.vat.validate({
  vatNumber: "NL123456789B01",
  requestId: "my-trace-id-123",
});

result = avatcado.vat.validate("NL123456789B01", request_id="my-trace-id-123")

Getting Started

Core Concepts

Guides

Errors

Response Format

Response Format

Success response

`data` fields

Error response

`error` fields

`meta` fields

Batch items

Response headers

Request ID header

​Response Format

​Success response

​data fields

​Error response

​error fields

​meta fields

​Batch items

​Response headers

​Request ID header

Response Format

Success response

`data` fields

Error response

`error` fields

`meta` fields

Batch items

Response headers

Request ID header