RpcStatusException class base

An exception thrown from an RPC handler to return a specific gRPC status code to the caller.

When a handler throws RpcStatusException, the framework serialises it into a gRPC trailer with statusCode, message, and optional structured details instead of the generic INTERNAL (13) status.

Structured details are sent via the grpc-status-details-bin trailer header as a protobuf-encoded google.rpc.Status message, making them wire-compatible with standard gRPC clients.

Future<Response> getUser(Request req, {RpcContext? context}) async {
  final user = await db.find(req.id);
  if (user == null) {
    throw RpcStatusException(
      RpcStatus.notFound,
      'user not found',
      details: [
        RpcErrorInfo(reason: 'USER_NOT_FOUND', domain: 'myapp.v1'),
      ],
    );
  }
  return Response(user: user);
}

Inheritance

• Object
• RpcException
• RpcStatusException

Implementers

• RpcCancelledException
• RpcCircuitBreakerOpenException
• RpcClosedException
• RpcDeadlineExceededException
• RpcFrameException
• RpcMetadataViolationException
• RpcNoConnectionException
• RpcRateLimitException

Constructors

RpcStatusException(RpcStatus statusCode, String message, {List<RpcErrorDetail> details = const []})

Creates an RPC status exception.

const

RpcStatusException.atCapacity(String message)

RESOURCE_EXHAUSTED for a limit that frees up by itself -- a stream or handler ceiling -- with the RpcRetryInfo that marks it as such.

RpcStatusException.fromTrailer(int code, String message, {Uint8List? detailsBin})

Reconstructs an RpcStatusException from wire data.

factory

Properties

details → List<RpcErrorDetail>

Structured error details sent via grpc-status-details-bin.

final

hashCode → int

The hash code for this object.

no setter, inherited

isPushback → bool

Whether this is the server pushing back: an RpcRateLimitException, or RESOURCE_EXHAUSTED carrying an RpcRetryInfo.

no setter

message → String

Human-readable description of the error.

final, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

statusCode → RpcStatus

The gRPC status; RpcStatus.code is its number on the wire.

final

statusDetailsBin → Uint8List?

Encodes details into a google.rpc.Status binary for the grpc-status-details-bin trailer. Returns null if no details.

no setter

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited