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 circuit breaker toward the upstream is open: recent calls failed repeatedly, so the calling service fails fast without contacting the upstream until it recovers.

Example Response

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

The detail field names the upstream by its logical role only (for example admin-api) 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.

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, the failure was transient (no breaker open) and a normal backoff applies.

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.