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-After header or exponential backoff retry strategy.
  • Extends HttpException to include URI, detailed context, and stack information.

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
Implemented types

Constructors

ServiceUnavailableException({Map<String, dynamic>? details, Exception? originalException, StackTrace? originalStackTrace, int statusCode = 503, Uri? uri})
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