> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avatcado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# upstream_member_state_unavailable

> Error: A specific VIES member state tax authority is down

# upstream\_member\_state\_unavailable

<Info>HTTP Status: **503 Service Unavailable**</Info>

## Example response

```json theme={null}
{
  "error": {
    "code": "upstream_member_state_unavailable",
    "message": "VIES member state FR is currently unavailable",
    "docs_url": "https://docs.avatcado.com/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`](/errors/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?

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

## Billing

This error is **not counted against your monthly quota**. When no fallback can be served, the API automatically refunds the request so you are not charged for an unanswered call. See [Non-billable failures](/rate-limits#non-billable-failures).

If a stale fallback was served instead (HTTP `200` with `meta.stale: true`), the request **does** count, since you received usable data.

## 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/](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, Avatcado may serve a stale cached result with `source_status: "unavailable"` instead of this error

## Catching this error with the SDKs

<CodeGroup>
  ```typescript @avatcado/node theme={null}
  import Avatcado, { UpstreamError } from '@avatcado/node';

  const avatcado = new Avatcado('avat_live_your_api_key');
  const { data, error } = await avatcado.vat.validate({ vatNumber: '...' });

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

  ```python Python theme={null}
  from avatcado import Avatcado, UpstreamError

  avatcado = Avatcado("avat_live_your_api_key")

  try:
      result = avatcado.vat.validate("...")
  except UpstreamError as e:
      print(e.message)
      print(f"Retry after {e.retry_after} seconds")
  ```
</CodeGroup>