BadGatewayException class

A specialized HttpException representing an invalid or failed response from an upstream server, corresponding to the HTTP 502 Bad Gateway status.

Overview

The BadGatewayException indicates that a server acting as a gateway or proxy
received an invalid response or an error from an upstream service, API,
or backend it attempted to contact while fulfilling a request.

This typically occurs when the gateway successfully connects to the upstream
but receives an unexpected, malformed, or non-compliant HTTP response, or when
the upstream terminates the connection prematurely.

Example

Future<void> forwardRequest(HttpRequestProvider request) async {
  try {
    final response = await httpClient.sendUpstream(request);
    if (response.statusCode >= 500) {
      throw BadGatewayException(
        'Upstream service responded with ${response.statusCode}',
        uri: request.getUri(),
      );
    }
  } on SocketException catch (e) {
    throw BadGatewayException(
      'Failed to connect to upstream service',
      details: {'cause': e.message},
      uri: request.getUri(),
    );
  }
}

Common Scenarios

  • The upstream API returns an invalid or malformed HTTP response
  • The backend unexpectedly closes the connection or sends a protocol error
  • Reverse proxies like NGINX or Jetleaf's internal gateways encounter a misbehaving backend
  • The upstream service crashes or produces incomplete responses

Integration Example

try {
  await dispatcher.dispatch(request, response);
} on BadGatewayException catch (e) {
  response.statusCode = 502;
  response.getOutputStream().writeString('Bad Gateway: ${e.message}');
}

Design Notes

  • Maps directly to HTTP 502 Bad Gateway as defined in RFC 7231 §6.6.3.
  • Indicates a proxy or gateway-layer error rather than a client or business logic failure.
  • Extends HttpException to propagate contextual metadata such as uri, details,
    and underlying originalException information.
  • Useful for microservice orchestration, reverse proxies, and API composition layers.

Summary

The BadGatewayException provides a consistent way for Jetleaf applications
to represent upstream service communication errors, supporting robust and
transparent error propagation in distributed or proxy-based architectures.

Inheritance
Implemented types

Constructors

BadGatewayException(String message, {Map<String, dynamic>? details, Exception? originalException, StackTrace? originalStackTrace, int statusCode = 502, Uri? uri})
A specialized HttpException representing an invalid or failed response from an upstream server, corresponding to the HTTP 502 Bad Gateway status.

Properties

cause → Object?
The underlying cause of this exception, if any.
finalinherited
details → Map<String, dynamic>?
Additional contextual information about the error.
finalinherited
hashCode → int
The hash code for this object.
no setterinherited
message → String
The message describing the error.
finalinherited
originalException → Exception?
The underlying exception that caused this FluxException.
finalinherited
originalStackTrace → StackTrace?
The stack trace from the original exception.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
stackTrace → StackTrace
The associated stack trace.
finalinherited
statusCode → int
The HTTP status code returned by the server, when applicable.
finalinherited
uri → Uri?
The URI of the HTTP request that triggered this exception.
finalinherited

Methods

getCause() → Object
The cause of this exception, if any.
inherited
getMessage() → String
The message associated with this exception.
inherited
getStackTrace() → StackTrace
The stack trace associated with this exception.
inherited
getStatus() → HttpStatus
Resolves the corresponding HttpStatus for this object, if available.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toJson() → Map<String, Object>
inherited
toMap() → Map<String, dynamic>
Converts this exception into a serializable map representation.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited