PayPal, Inc.

jackhays@paypal.com

This document defines a new HTTP 5xx status code, 528 (Outbound Dependency Failed), used to indicate that a server received, parsed, and processed a request correctly, but could not complete it because a required downstream dependency malfunctioned or was in a non-transient failure state. Unlike 500 (Internal Server Error), which SHOULD be reserved for actual faults within the responding service (including improper error handling), 528 explicitly signals that the responding service operated as intended and the failure lies in a dependency. Unlike 503 (Service Unavailable), 528 does not imply a temporary condition expected to recover without intervention.

Introduction In distributed systems, services commonly rely on downstream resources (other services, data stores, message brokers) to fulfill client requests. When those dependencies fail, many implementations surface a generic 500 (Internal Server Error), conflating true internal faults with dependency failures and degrading observability and automated remediation. HTTP status codes such as 502 (Bad Gateway) and 504 (Gateway Timeout) describe failures in intermediary behavior on the inbound path, while 503 (Service Unavailable) communicates temporary unavailability. None precisely convey that the responding service behaved correctly yet could not complete the request due to a non-transient malfunction in an outbound dependency. This specification introduces 528 (Outbound Dependency Failed) to distinguish such conditions from internal failures (500) and from temporary unavailability (503).

Definition The 528 (Outbound Dependency Failed) status code indicates that the server successfully received, understood, and executed its own application logic for the request, but could not complete the response because a required downstream or external dependency experienced a failure that is not presumed to be transient.

Example 528 Response HTTP/1.1 528 Outbound Dependency Failed Content-Type: application/json { "error": "OUTBOUND_DEPENDENCY_FAILED", "dependency": "user-profile-service", "dependency_status": 500, "message": "Downstream dependency returned HTTP 500", "correlation_id": "abc-123" }

The 528 code allows clients and operators to differentiate:

• 500 — internal error within this service (including improper error handling)
• 503 — temporary unavailability (retry may be appropriate)
• 528 — this service operated correctly; a required downstream dependency failed in a condition not assumed to be temporary

Semantics and Use Servers SHOULD return 528 when all of the following are true:

• The server's own request handling logic executed as intended.
• Completion of the response required a call to a downstream or external dependency.
• The dependency failed (for example, returned a 5xx status, was misconfigured, was unreachable with a non-transient cause, or produced invalid data) in a way that prevents successful completion.

The 528 status code is not a signal of transient unavailability. Clients SHOULD NOT assume retry will succeed without operator or system intervention to restore the failing dependency. In contrast, 503 commonly represents a temporary condition for which retry with backoff may be appropriate. Implementations MAY include machine-readable fields identifying the affected dependency and any observed downstream status code or other relevant diagnostics. Care should be taken to avoid leaking sensitive topology details (see Security Considerations).

Interoperability Notes 502 (Bad Gateway) describes an intermediary receiving an invalid response from an upstream server on the inbound path. It does not semantically cover an origin service’s failure to complete due to its own outbound dependency malfunction. 503 (Service Unavailable) is widely interpreted as a temporary condition (overload or maintenance) that may self-resolve. The 528 status code makes no such implication and is intended for dependency failures that typically require corrective action.

Operational Guidance For automated remediation, a 528 response SHOULD trigger circuit-breaker transitions, alerting, or failover logic rather than blind immediate retries. Downstream recovery SHOULD be confirmed prior to resuming normal traffic patterns. Services SHOULD continue to use 500 exclusively for actual internal faults, including unhandled exceptions and improper catch/log/500 patterns. Misrouted 500 responses mask dependency failures and undermine SLO-driven operations.

Security Considerations Revealing dependency names, network locations, or detailed failure diagnostics in responses may expose internal topology. Servers SHOULD minimize sensitive details in public-facing responses and prefer correlation identifiers, with full diagnostics recorded in logs accessible to operators.

Conformance and Requirements Language The key words “MUST”, “MUST NOT”, “SHOULD”, “SHOULD NOT”, and “MAY” in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

IANA Considerations This document requests the registration of the following entry in the “Hypertext Transfer Protocol (HTTP) Status Code Registry”:

Value: 528 Description: Outbound Dependency Failed Reference: [this document]

Acknowledgments The author thanks members of the IETF HTTP Working Group for discussions on status code semantics and the operational boundary between origin services and their dependencies.

Normative