Response Format

Consistent envelope pattern on every API response

Response Format

Every Vatly 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"
    },
    "consultation_number": "WAPIAAAAA1BBB2",
    "requested_at": "2026-03-06T12:00:00Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "cached": 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 (when valid and available)
company.name	string	Registered company name
company.address	string | null	Registered address
consultation_number	string | null	VIES/HMRC consultation number (Business and Scale tiers only)
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.vatly.dev/errors/invalid_vat_format"
  },
  "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

meta fields

Present on every response — success or error.

Field	Type	Description
request_id	string	Unique request identifier (UUID)
cached	boolean | null	Whether the result came from cache (success only)
cached_at	string | null	ISO 8601 timestamp of the cached result (when cached)
stale	boolean | null	true when serving an expired cached result due to upstream failure
mode	string | null	"test" when using a test key, omitted for live keys

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)
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 vtly_live_your_api_key" \
  -H "X-Request-Id: my-trace-id-123" \
  "https://api.vatly.dev/v1/validate?vat_number=NL123456789B01"