Skip to content

Upstream Service Unavailable

URI: https://docs.ankatech.co/errors/upstream-unavailable
HTTP Status: 502 Bad Gateway

When you see this

The service you called is running, but it depends on another internal AnkaSecure service (an "upstream") to complete your request, and that upstream failed. Typical example: a key listing or key export request proxied from the Core API to the Admin API while the Admin API is down.

Common Causes

  • The upstream service is down, restarting, or unreachable (connection failure).
  • The upstream service returned an internal error (5xx) for the proxied call.
  • The upstream service returned an invalid or empty response that the calling service could not process.
  • The upstream answered with a response larger than its contract allows. Every internal client states the largest answer it reads, derived from what the upstream may legitimately send; a larger one is the upstream's failure. The detail says so: The administration service answered with a response larger than its contract allows. Retrying returns the same answer until the upstream is fixed.
  • The circuit breaker toward the upstream is open: recent calls failed repeatedly, so the calling service fails fast without contacting the upstream until it recovers.
  • The upstream refused the platform's own service-to-service credential (401) or found it insufficiently scoped (403). This is a platform-side misconfiguration, not a decision about your authorization, so it is reported as 502 and never as a 401/403 or a client 400.
  • A pooled keep-alive connection to the upstream was reused just as the upstream closed it, so a single call died on a connection that looked usable.

The Retry-After header separates the open circuit breaker from every other cause on this list — and that is the only split it makes. A 502 with Retry-After is the open circuit breaker: the calling service is failing fast, every call on that internal edge is failing for a fixed interval, and the wait is the hint's value. A 502 without Retry-After is any of the remaining causes: the upstream is down, restarting or unreachable, it returned a 5xx or an unusable response, it refused the platform's own S2S credential, or a pooled keep-alive connection was reused just as it closed. Only that last one is a single-call fault that the next attempt clears, so an absent header does not mean the failure was momentary — an upstream that is hard down returns this same header-less 502 to every attempt until it comes back, and a credential misconfiguration returns it until an operator fixes the deployment. Treat the absent header as the platform has no wait to suggest, and back off exponentially yourself (see How to Resolve below); retrying it in a tight loop only adds load to a dependency that is already failing. Do not read the first case as the second either: a burst of 502s carrying Retry-After will not clear by retrying sooner. Both mechanisms live in the shared service-to-service layer and can occur on any internal edge, so neither is a property of the particular operation you called.

Response Example

{
  "type": "https://docs.ankatech.co/errors/upstream-unavailable",
  "title": "Upstream Service Unavailable",
  "status": 502,
  "detail": "The administration service is temporarily unavailable.",
  "instance": "/api/v3/key-management/keys"
}

The detail field names the upstream by its role only — the cryptographic service, the administration service, the authentication service, the licence server, the notification delivery service or a monitored platform service — never by an internal service name, host or address, and instance is the path of the request you made. Use the X-Request-Id response header to correlate the failure with server-side logs when contacting support.

This body carries exactly the five RFC 9457 members shown above — no requestId and no timestamp member. It is produced by the shared upstream-fault mapper, which is deliberately independent of the per-service problem body; correlate through the X-Request-Id header instead.

The 502 is also the destination for every upstream status that is not relayable. Only 400, 402, 404, 409 and 422 are re-presented as a client fault with the upstream's own type/title/detail; everything else — including 401 and 403 — becomes this 502. See S2S Relay Envelope.

Retry-After Header

When the circuit breaker toward the failing upstream is open, the response includes a Retry-After header with the number of seconds to wait before retrying:

Retry-After: 27

The value is an integer between 1 and the breaker's configured open-state wait (30 seconds by default). When the header is absent, no breaker is open on that edge — which tells you the platform has no wait to suggest, not that the failure was transient. Apply your own exponential backoff, as described below.

How to Resolve

  1. This error IS retryable - the request itself is valid; the platform's dependency failed.
  2. If a Retry-After header is present, wait at least that many seconds before retrying.
  3. If the header is absent, retry with exponential backoff (for example 1s, 2s, 4s).
  4. Do not modify the request payload - the failure is independent of your input.
  5. If the error persists beyond a few minutes, check the service status page or contact support with the X-Request-Id value.
  • Service Unavailable (503) - The service you called is itself unavailable (maintenance, overload). 502 means the service you called is fine but its internal dependency failed.
  • Upstream Service Timeout (504) - The upstream did not answer within the operation's deadline. 502 means it failed outright or could not be reached.

AnkaSecure clients (SDK and CLI) honor the Retry-After hint automatically during their built-in retry sequence.