ServiceUnavailableException class
A specialized HttpException representing a temporary service outage,
corresponding to the HTTP 503 Service Unavailable status.
Overview
The ServiceUnavailableException is thrown when the server is currently unable to handle the request due to temporary overload or scheduled maintenance.
It signals that the condition is temporary and that the client may
retry the request after a certain delay (optionally indicated via a
Retry-After response header).
Example
Future<void> handleRequest(HttpRequestProvider request, HttpResponseProvider response) async {
if (!database.isAvailable) {
throw ServiceUnavailableException(
'Database temporarily unavailable',
details: {'retryAfter': Duration(seconds: 30)},
);
}
await processRequest(request, response);
}
Common Scenarios
- Backend dependencies (e.g., database, cache, microservice) unavailable
- Scheduled system maintenance or scaling downtime
- Load balancer or service mesh temporarily throttling requests
- Circuit breaker or health check preventing access
Integration Example
try {
await dispatcher.dispatch(request, response);
} on ServiceUnavailableException catch (e) {
response.statusCode = 503;
response.getOutputStream().writeString('Service temporarily unavailable: ${e.message}');
}
Design Notes
- Maps directly to HTTP 503 Service Unavailable as defined in
RFC 7231 §6.6.4. - Intended for transient server conditions where recovery is expected.
- Often used with a
Retry-Afterheader or exponential backoff retry strategy. - Extends HttpException to include URI, detailed context, and stack information.
Related Exceptions
- InternalServerErrorException – for unexpected internal failures (500)
- GatewayTimeoutException – for upstream timeouts (504)
- BadGatewayException – for proxying or upstream server errors (502)
Summary
The ServiceUnavailableException serves as Jetleaf's standardized way to signal temporary service interruptions while allowing clients to gracefully handle retry logic or fallback behavior.
- Inheritance
-
- Object
- Error
- HttpException
- ServiceUnavailableException
- Implemented types
Constructors
-
A specialized HttpException representing a temporary service outage,
corresponding to the HTTP 503 Service Unavailable 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