HttpError class

A failure that survives the hop.

A status code alone tells a caller that something went wrong, not what. Two different 404s — an unknown user and an unknown organisation — are indistinguishable to the service calling you, so its only options are to give up or to match on a human-readable message that was never meant to be an API. This carries a stable code alongside the status, so the caller can branch on the thing that actually differs.

throw const HttpError.notFound(
  code: 'user_not_found',
  message: 'No user with that id',
);

Serialises to the envelope below, mirroring the {"data": ...} wrapper that successful responses already use:

{"error": {"code": "user_not_found", "message": "No user with that id"}}

Throwing this is opt-in. Nothing changes the framework's existing plain-text default responses, so a client that reads them today keeps working; a caller sees code only for handlers that chose to raise one.

Implemented types

Constructors

HttpError({required int statusCode, required String code, required String message, Map<String, Object?> details = const {}})
const
HttpError.badRequest({required String code, required String message, Map<String, Object?> details = const {}})
const
HttpError.conflict({required String code, required String message, Map<String, Object?> details = const {}})
const
HttpError.forbidden({required String code, required String message, Map<String, Object?> details = const {}})
const
HttpError.internal({required String code, required String message, Map<String, Object?> details = const {}})
const
HttpError.notFound({required String code, required String message, Map<String, Object?> details = const {}})
const
HttpError.unauthorized({required String code, required String message, Map<String, Object?> details = const {}})
const
HttpError.unprocessable({required String code, required String message, Map<String, Object?> details = const {}})
const

Properties

code → String
A stable, machine-readable identifier — user_not_found, not User not found.
final
details → Map<String, Object?>
Extra machine-readable context — which field failed validation, how long to wait.
final
hashCode → int
The hash code for this object.
no setterinherited
message → String
A human-readable explanation, for logs and developers.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
statusCode → int
The HTTP status this failure responds with.
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toEnvelope() → Map<String, Object?>
The wire form.
toString() → String
A string representation of this object.
override

Operators

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