W System / VIES error codes explained

VIES error codes explained: MS_UNAVAILABLE, MS_MAX_CONCURRENT_REQ, TIMEOUT and more

Short answer: VIES has six documented fault codes. Only INVALID_INPUT means your request is wrong; the other five (MS_UNAVAILABLE, MS_MAX_CONCURRENT_REQ, GLOBAL_MAX_CONCURRENT_REQ, SERVICE_UNAVAILABLE, TIMEOUT) mean the answer is unknown right now. Never treat them as "VAT number invalid": retry with backoff and keep the customer moving.

VIES code	Official meaning (EC WSDL)	Is the VAT number invalid?	What to do	W System answer
`INVALID_INPUT`	The country code is invalid or the VAT number is empty	Unknown: the request itself is malformed	Fix the input (2-letter prefix, EL for Greece, no spaces); don't retry unchanged	`invalid_format` before VIES is called, with the expected format; otherwise `status: error`
`MS_UNAVAILABLE`	The member state's application is not replying or not available	No: unknown	Retry later; don't block the customer; keep the order pending	Retries with backoff, then a flagged fallback (official national source or last dated VIES result) or `member_state_unavailable`, `valid: null`
`MS_MAX_CONCURRENT_REQ`	Too many concurrent requests for this member state	No: unknown	Back off and retry; queue bulk checks per country	Same as `MS_UNAVAILABLE`
`GLOBAL_MAX_CONCURRENT_REQ`	Too many concurrent requests to VIES overall	No: unknown	Back off and retry with jitter	Same as `MS_UNAVAILABLE`
`SERVICE_UNAVAILABLE`	Network or VIES web application error	No: unknown	Retry later	Same as `MS_UNAVAILABLE`
`TIMEOUT`	VIES got no reply from the member state in time	No: unknown	Retry later; use a client timeout above 10 s	Same as `MS_UNAVAILABLE`

Meanings are paraphrased from the European Commission's checkVatService WSDL (checked 2026-10-26). Live member-state status: our VIES status page.

Handling them in code

A safe pattern: treat valid: true and valid: false from a successful answer as final, put the five transient codes into a retry queue with exponential backoff (for example 1 s, 2 s, 4 s, then minutes), and never cache an error as "invalid".

TRANSIENT = {"MS_UNAVAILABLE", "MS_MAX_CONCURRENT_REQ", "GLOBAL_MAX_CONCURRENT_REQ",
             "SERVICE_UNAVAILABLE", "TIMEOUT"}
if error in TRANSIENT:
    status = "unknown"      # retry later, don't reject the customer
elif error == "INVALID_INPUT":
    status = "bad_request"  # fix the country prefix / number

Or let an API do the retries

We make W System, an EU VAT check API. It retries VIES with backoff and, when a member state stays down, answers from that country's official source (PL, CZ, FI, FR) or the last dated VIES result, flagged with fallback: true. Otherwise you get member_state_unavailable, valid: null and retry_after_seconds, never a false "invalid". Free: 20 calls a day per IP, or a free key with 500 units a month.

curl "https://api.wsystem.dev/verify?vat=IE6388047V"

Questions and answers

What does MS_UNAVAILABLE mean in VIES?

The member state's VAT database did not answer VIES. It says nothing about the number: treat the result as unknown, not invalid, and check again later. The EC's VIES page shows which member states are currently down.

What is MS_MAX_CONCURRENT_REQ?

VIES refused the request because too many requests are already open for that member state. It is throttling, not a verdict on the VAT number. Wait, retry with backoff, and spread bulk checks over time; MS_MAX_CONCURRENT_REQ_TIME and GLOBAL_MAX_CONCURRENT_REQ_TIME are variants that W System treats the same way.

Should I reject a customer when VIES returns an error?

No. Only valid: false from a successful VIES answer means the number is not registered for intra-EU trade. For the six error codes, keep the order pending or charge VAT provisionally and re-check, depending on your tax adviser's guidance.

Why does my VIES library say 'invalid' when VIES is down?

Some libraries catch the timeout or fault and return is_valid=False. Check the library's error or log field and map these codes to 'unknown'. W System never returns valid: false for an outage; it returns member_state_unavailable with valid: null and retry_after_seconds.

Do these errors come from the REST API too?

Yes. The VIES REST endpoint (/check-vat-number) returns the same codes in userError or errorWrappers; the SOAP service returns them as SOAP faults.

Facts checked 2026-10-26. W System is the maker of this product. Not affiliated with the European Commission. Not legal or tax advice.