Response envelope
All VerifyVAT endpoints return the same top-level JSON structure, referred to as the common response envelope.
The envelope describes the outcome of the request at the VerifyVAT system level, while each endpoint places its own data inside the data field.
A common envelope follows this shape:
# EndpointResponse being the endpoint-specific response data typeEnvelope<EndpointResponse>: success: boolean timestamp: number
code: string message: string? # only present for errors
data: EndpointResponse | nullThis separation is intentional:
successandcodetell you whether VerifyVAT was able to process the request.- The contents of
datatell you what happened inside the endpoint's domain (verification result, candidate matches, supported IDs, etc.).
Envelope fields
| Field | Meaning |
|---|---|
success | true if the request was handled successfully by VerifyVAT (even if the registry behind it fails). false for request-level errors such as malformed input, missing API key, or hard rate limits. |
timestamp | Milliseconds timestamp (Unix epoch) when the response was generated. |
code | Machine-readable status code ( ok, bad-request, invalid-api-key, daily-limit-exceeded, etc.). |
message | Optional human-readable summary, for errors. Not guaranteed stable for programmatic use. |
data | Endpoint-specific payload. null if the request failed at the top level, or when a valid request has nothing to return. |
1. Request-level errors appear in the envelope
In case of malformed JSON, missing or invalid API key, or hard rate limits, the entire request fails.
The response will contain success = false, a specific error code, and data = null.
2. Endpoint-level issues appear inside data
In case of issues that occur inside the endpoint's logic, the request still succeeds at the VerifyVAT system level. These include scenarios such as partial data, degraded conditions, or registry-level failures.
The response will contain success = true, code = "ok", and data with details about the issue.
For example, Verify an ID exposes registry issues through data.process.output.
Response headers
Operational metadata is exposed via HTTP headers to avoid polluting the response body.
| Header | Meaning |
|---|---|
CW-Trace-Id | Unique identifier for the request. Use it for logging or support. |
CW-Billable-Overage | true or false. Indicates whether the request counted as billable overage. |
CW-Rate-Limited-By | Present when blocked by a rate limiter. Either burst, daily, or monthly. |
CW-Rate-Limited-Until | Milliseconds timestamp when the rate limit will reset, if applicable. |
Retry-After | Standard HTTP header with seconds until the rate limit resets, if applicable. |
These headers allow you to correlate logs via CW-Trace-Id, track billable overage via CW-Billable-Overage, and implement exponential backoff retry logic via CW-Rate-Limited-* and Retry-After.
Our official SDKs include built-in support for logging the trace ID and handling rate limits. If you implement your own client, make sure to capture these headers for observability and error handling. See SDK overview for more details.