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.
Related Exceptions
- GatewayTimeoutException – when an upstream fails to respond in time (504)
- ServiceUnavailableException – for temporarily overloaded or unavailable services (503)
- InternalServerErrorException – for internal server logic failures (500)
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
-
- Object
- Error
- HttpException
- BadGatewayException
- 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