Skip to main content

​
upstream_error

HTTP Status: 503 Service Unavailable

​
Example response

{
  "error": {
    "code": "upstream_error",
    "message": "HMRC returned 500 Internal Server Error",
    "docs_url": "https://docs.vatly.dev/errors/upstream_error"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

​
What happened?

The upstream VAT validation service (HMRC) returned an unexpected error status code. This happens when:
  • HMRC’s API is experiencing internal errors
  • HMRC returned a non-success, non-404 HTTP status
  • There’s a temporary issue with HMRC’s infrastructure
This error currently applies to GB VAT numbers validated via HMRC. For EU numbers, connectivity issues are reported as upstream_unavailable.

​
How to fix

  1. Retry after the Retry-After header — The response includes Retry-After: 10, telling you to wait 10 seconds before retrying
  2. Check the message field — It includes the specific HTTP status HMRC returned, which can help diagnose the issue
  3. Use the X-Request-Id — Include it in any support requests for faster debugging

​
Common mistakes

  • Retrying immediately in a tight loop — Add exponential backoff between retries
  • Treating this as a permanent failure — Upstream errors are almost always temporary
  • Confusing with upstream_unavailable — upstream_error means the service responded with an error; upstream_unavailable means it couldn’t be reached at all

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