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, rate-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 | Identifies the limit that blocked the request: usage (usage slots), burst (burst slots), or concurrency (concurrency slots). If several limits block the request, priority is usage slots, then burst slots, then concurrency slots. monthly indicates that an account without an active plan has exhausted its included allowance. |
CW-Rate-Limited-Until | Suggested retry time as a Unix timestamp in milliseconds. Omitted whenever concurrency also blocks the request. Does not reserve capacity or guarantee that a retry will succeed. |
Retry-After | Minimum suggested wait before retrying, in whole seconds. Accounts for when usage and burst slots become available again. For concurrency alone, the suggested wait is one second. |
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.