Skip to content

Upstream Service Timeout

URI: https://docs.ankatech.co/errors/upstream-timeout
HTTP Status: 504 Gateway Timeout

When you see this

The service you called depends on another internal AnkaSecure service (an "upstream") to complete your request, and that upstream did not respond within the operation's deadline. The upstream may be healthy but slow, overloaded, or stalled.

Common Causes

  • The upstream service is overloaded and responding slower than the per-operation deadline allows.
  • A long-running query or lock contention on the upstream side delayed the response.
  • Network latency or packet loss between the services.
  • The upstream is in a degraded state (for example garbage-collection pauses or resource exhaustion) without being fully down.

Example Response

{
  "type": "https://docs.ankatech.co/errors/upstream-timeout",
  "title": "Upstream Service Timeout",
  "status": 504,
  "detail": "The admin-api service did not respond in time.",
  "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

Repeated timeouts open the circuit breaker toward the upstream. While the breaker is open, subsequent failures include 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). A 504 from an isolated slow call typically carries no Retry-After header.

How to Resolve

  1. This error IS retryable - the operation timed out, it was not rejected.
  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. Be aware the timed-out operation MAY have completed on the upstream after the deadline - for idempotent reads this is harmless; for writes, verify state before blindly resubmitting.
  5. If timeouts persist, the upstream is likely degraded - check the service status page or contact support with the X-Request-Id value.

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