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 at all. This happens when:
  • VIES (EU) or HMRC (UK) is down for maintenance
  • A network timeout occurred while connecting to the upstream service
  • 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 or HMRC) is having issues, not the Vatly API itself

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