> ## Documentation Index > Fetch the complete documentation index at: https://docs.avatcado.com/llms.txt > Use this file to discover all available pages before exploring further. # Response Format > Consistent envelope pattern on every API response # 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 ```json theme={null} { "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, "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` | VIES/HMRC consultation number. Only present when `requester_vat_number` is provided. Not available for CH, LI, NO, or AU validations | | `requested_at` | `string` | ISO 8601 timestamp of the validation | ## Error response ```json theme={null} { "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" }, "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) | | `request_duration_ms` | `number` | Total request processing time in milliseconds (success responses only) | | `cached` | `boolean` | Whether the result came from cache. Omitted when not applicable | | `cached_at` | `string` | ISO 8601 timestamp of the cached result. Omitted when not cached | | `stale` | `boolean` | `true` when serving an expired cached result due to upstream failure. Omitted when not stale | | `source_status` | `string` | Upstream data source reliability: `"live"` (fresh result), `"unavailable"` (upstream down, stale cache served), or `"degraded"` (possible silent false negative). Applies to all upstream sources (VIES, HMRC, BFS, Bronnysund, or ABR). Only present on fresh upstream lookups and stale fallbacks | | `mode` | `string` | `"test"` when using a test key. Omitted for live keys | ## Batch items Each item in a [batch validation](/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 `meta` contains the `vat_number` that failed Per-item `meta` contains cache fields (`cached`, `cached_at`, `stale`) and `source_status` when applicable. 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. ```bash curl theme={null} 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" ``` ```typescript @avatcado/node theme={null} const { data, error } = await avatcado.vat.validate({ vatNumber: "NL123456789B01", requestId: "my-trace-id-123", }); ``` ```python Python theme={null} result = avatcado.vat.validate("NL123456789B01", request_id="my-trace-id-123") ```