How do I tell an invalid VAT number apart from an error?

A well-formed VAT number that simply isn’t registered returns HTTP 200 with valid: false – that’s a normal answer, not an error.

Errors are separate

An error means vatnode could not give you a verdict, or could not accept the request. The codes you will meet most:

• INVALID_FORMAT (400): the string isn’t a valid VAT ID shape, and it never reached VIES.
• VIES_UNAVAILABLE (503): the EU system was down.
• RATE_LIMITED (429): you hit your monthly quota.
• INVALID_REQUESTER (422): the requester VAT you configured in dashboard Account details is itself invalid in VIES.

Every error response has the same shape, with a machine-readable code, a human-readable message and a requestId:

{"error": {"code": "INVALID_FORMAT", "message": "Invalid VAT ID format for DE", "requestId": "req_abc123"}}

How to branch in code

• HTTP 200: read valid. true means registered and active, false means the number is not registered – a business answer you can show to the customer.
• Other status: read error.code. Fix the input for 400, retry later for 503, and upgrade or wait for the next period for 429.
• Log the requestId from every error and include it in support tickets.

The mistake to avoid is treating a 503 as ‘invalid’. A valid: false is a verdict; VIES_UNAVAILABLE is the absence of one.

The error reference has the full response shape, every HTTP status code vatnode returns, and how to handle each one.