Skip to main content

​
upstream_member_state_unavailable

HTTP Status: 503 Service Unavailable

​
Example response

{
  "error": {
    "code": "upstream_member_state_unavailable",
    "message": "VIES member state FR is currently unavailable",
    "docs_url": "https://docs.vatly.dev/errors/upstream_member_state_unavailable"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

​
What happened?

VIES reported that the specific EU member state’s tax authority backend is unavailable. VIES is a gateway that routes to individual national databases. When one is down, only VAT numbers from that country are affected. This is different from upstream_unavailable, which means the entire upstream service (VIES, HMRC, BFS, BRREG, or ABR) is unreachable. Here, VIES itself is working but the member state backend is not. Common VIES availability errors that trigger this:
  • MS_UNAVAILABLE - the member state database is offline
  • MS_MAX_CONCURRENT_REQ - the member state is overloaded
  • TIMEOUT - the member state did not respond in time
  • SERVICE_UNAVAILABLE - the VIES service itself is down
  • GLOBAL_MAX_CONCURRENT_REQ - VIES-wide concurrency limit reached

​
Why didn’t I get a stale cached result?

Vatly serves stale cached results with meta.source_status: "unavailable" when possible. You only see this 503 error when Vatly has never validated this VAT number before and has no cached result to fall back on.

​
How to fix

  1. Retry after the Retry-After header: Use exponential backoff, doubling each time up to 60 seconds
  2. Check VIES status: https://ec.europa.eu/taxation_customs/vies/ to see if the specific country shows as unavailable
  3. Try again later: Member state outages are usually temporary (minutes to hours)
  4. Handle gracefully: Show users a message like “VAT validation for [country] is temporarily unavailable”

​
Common mistakes

  • Treating this as a permanent failure: Member state outages are transient. Always retry
  • Not checking meta.source_status: On subsequent requests for the same VAT number, Vatly may serve a stale cached result with source_status: "unavailable" instead of this error

​
Catching this error with the SDKs

import Vatly, { UpstreamError } from '@vatly/node';

const vatly = new Vatly('vtly_live_your_api_key');
const { data, error } = await vatly.vat.validate({ vatNumber: '...' });

if (error instanceof UpstreamError) {
  console.log(error.message);
  console.log(`Retry after ${error.retryAfter} seconds`);
}