Error handling

VerifyVAT uses a clear and predictable error model.
All errors follow the Response envelope common structure and are made up of:

Errors always originate at one of three layers:

1. Request validation
   Malformed JSON, missing fields, invalid parameters, etc.

2. Authentication & subscription
   Missing/invalid API key, inactive plan, quota exhaustion.

3. Internal execution errors
   Rare, usually related to external registry failures or unexpected exceptions.

Regardless of the origin, the response format remains identical.
Only code and message will differ.

A typical error response looks like this:

1
POST https://api.verifyvat.com/v1/verify
2
Content-Type: application/json
3
x-api-key: invalid_key
4
{
5
    "success": false,
6
    "timestamp": {current-time-ms},
7
    "code": "invalid-api-key",
8
    "message": "Invalid API key",
9
    "data": null
10
}

This page describes how to interpret these errors and how to respond to them in your integration.

Canonical error codes

These result codes are stable and safe for programmatic use.
They appear in the top-level code property and reflect the final outcome of the request.

The message field always contains a human-readable explanation of the error, should you need it for debugging or support.

Registry-level failures

Registry failures do not produce top-level API errors. Instead, they appear inside process.sources[] and process.output of the Verify an ID endpoint payload. As documented in Response envelope, these failures are considered part of normal operation. The top-level request will still succeed. For fallback related behaviour in case of error, see Caching and stale data.

Unexpected errors

Unexpected internal errors are rare, but they can happen. Internal errors do not leak stack traces or implementation details. If available, contact support with the request trace ID for further investigation. You can find it in the CW-Trace-Id response header.

Best practices

• Handle errors using code, not message
• Treat HTTP status as a hint, code is authoritative
• Inspect process.sources[] to understand registry-level behaviour for Verify an ID requests
• Retry only when HTTP status is 500 or registry failures indicate temporary unavailability
• Do not retry on 429 without backoff, these limits are enforced intentionally

Our official SDKs include built-in support for handling rate limits and retries with exponential backoff. If your language is not supported, you can implement similar logic based on the guidelines above. See SDK overview for reference implementations.