> ## 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_unavailable

> Error: upstream service (VIES, HMRC, BFS, Bronnysund, or ABR) is unreachable or returned an error

# upstream\_unavailable

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

## Example response

```json theme={null}
{
  "error": {
    "code": "upstream_unavailable",
    "message": "The upstream VAT validation service is currently unavailable",
    "docs_url": "https://docs.avatcado.com/errors/upstream_unavailable"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## What happened?

The upstream VAT validation service could not be reached, or it returned an unexpected error. This happens when:

* **VIES** (EU), **HMRC** (UK), **BFS UID Register** (CH/LI), **Bronnysund Register Centre** (NO), or **ABR** (AU) is down for maintenance
* A network timeout occurred while connecting to the upstream service
* The upstream service returned an unexpected HTTP error status
* An unexpected exception occurred during the validation request
* DNS resolution failed for the upstream service

## How to fix

1. **Retry after the `Retry-After` header**: The response includes `Retry-After: 10`, telling you to wait 10 seconds before retrying. Then use exponential backoff, doubling each time up to a maximum of 60 seconds
2. **Check upstream service status**:
   * VIES: [https://ec.europa.eu/taxation\_customs/vies/](https://ec.europa.eu/taxation_customs/vies/)
   * HMRC: [https://api-platform-status.production.tax.service.gov.uk/](https://api-platform-status.production.tax.service.gov.uk/)
   * BFS UID Register (CH/LI): [https://www.uid.admin.ch/](https://www.uid.admin.ch/)
   * Bronnysund Register Centre (NO): [https://www.brreg.no/](https://www.brreg.no/)
   * ABR (AU): [https://abr.business.gov.au/](https://abr.business.gov.au/)
3. **Handle gracefully**: Show users a message like "VAT validation is temporarily unavailable, please try again later"

## Common mistakes

* **No retry logic**: Always implement retries for 503 errors since they're transient by nature
* **Retrying too aggressively**: Use exponential backoff, not a tight loop
* **Blaming Avatcado**: This error means the third-party service (VIES, HMRC, BFS, Bronnysund, or ABR) is having issues, not the Avatcado API itself

## 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>

## Billing

This error is **not counted against your monthly quota**. When the upstream is unavailable and no cached or stale 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.

## Stale cache fallback

If Avatcado has a previous cached result for the same VAT number, it will serve that result with `meta.stale: true` instead of returning a 503 error. See [Caching](/caching#stale-cache-fallback) for details.

## Member state unavailability

When a specific VIES member state is down (rather than the entire VIES service), Avatcado detects this via the VIES `userError` field and serves stale cached results with `meta.source_status: "unavailable"` instead of returning a 503 error. If no stale cache exists, a `503` error with code [`upstream_member_state_unavailable`](/errors/upstream_member_state_unavailable) is returned instead.