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

Response Example

{
  "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.

This body carries exactly the five RFC 7807 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, 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, 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.