Loading

How to determine if a 503 is coming from the upstream or from Flex

Дата публикации: Apr 16, 2026
Описание

When a client receives a 503 error through Flex Gateway, it is often unclear which component in the request lifecycle triggered the failure. The error could be surfaced by:

  1. The Upstream Service: The backend is reachable but returns a 503.

  2. A Policy: A traffic management or security policy that blocks the request.

  3. The Gateway (Envoy): Flex Gateway can't establish a connection to the upstream, or no healthy instances are available.

Configuring the following policies allows you to "fingerprint" the response and capture granular metadata at the moment of failure.

Решение

Follow these steps to configure the diagnostic policies on your API instance.

Step 1: Configure Header Injection (External Tracking)

This policy helps you identify if the request successfully transitioned through the gateway's policy pipeline.

  1. In API Manager, navigate to API Instance > Policies > Add policy > Header Injection.

  2. Locate the Outbound Header Map (Headers sent back to the client).

  3. Add the following:

    • Key: X-Flex-Processed

    • Value: true

  4. Leave the Inbound Header Map empty.

  5. Validation:

    • Header Present: The response passed through the policy pipeline. The 503 came from either the Upstream or a Policy.

    • Header Absent: The 503 was generated internally by Envoy (e.g., connection timeouts or "no healthy upstream" scenarios).

Step 2: Configure Message Logging (Internal Diagnostics)

This policy captures specific DataWeave variables that reveal the "disposition" of the request.

  1. In API Manager, navigate to API Instance > Policies > Add policy > Message Logging.

  2. In the Logging Configuration section, add an item with the following parameters:

    • Configuration Name: response-diagnostics

    • Level: ERROR

    • Before Calling API: Unchecked (false)

    • After Calling API: Checked (true)

    • Conditional: #attributes.statusCode == 503

    • Message: ```dw #['status=' ++ attributes.statusCode ++ ' disposition=' ++ vars.requestDisposition ++ ' violationPolicy=' ++ vars.violation.policyName ++ ' method=' ++ vars.request.method ++ ' path=' ++ vars.request.requestPath]

Step 3: Analyze the Logs

Search your log aggregator (or Flex Gateway container logs) for the response-diagnostics entry to pinpoint the root cause:

Log DetailSource of 503Action
disposition=PROCESSEDUpstream BackendInvestigate the backend service health and logs.
disposition=VIOLATIONMuleSoft PolicyCheck violationPolicy in the log to see which policy triggered the error.
No log entry foundEnvoy InternalCheck Flex Gateway logs for response_flags. Common flags include UH (No healthy upstream) or UF (Upstream connection failure).

 

Номер статьи базы знаний

005318693

 
Загрузка
Salesforce Help | Article