Skip to main content

​
upstream_unavailable

HTTP Status: 503 Service Unavailable

​
Example response

{
  "error": {
    "code": "upstream_unavailable",
    "message": "The upstream VAT validation service is currently unavailable",
    "docs_url": "https://docs.vatly.dev/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:
  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 Vatly: This error means the third-party service (VIES, HMRC, BFS, Bronnysund, or ABR) is having issues, not the Vatly API itself

​
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`);
}

​
Stale cache fallback

If Vatly 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 for details.

​
Member state unavailability

When a specific VIES member state is down (rather than the entire VIES service), Vatly 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 is returned instead.