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

​
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. 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 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.