Error Responses

When a request fails and no exception catcher handles it, Revali sends one of two responses:

• An HttpError that your code throws is sent with its own status and a JSON body containing an error code. Use it when callers need to know which error happened.
• Anything else gets a default response: plain text, and 500 for an unhandled exception. Override defaultResponses on your app to change these.

Default Responses#

import 'package:revali_router/revali_router.dart';

@App()
final class MainApp extends AppConfig {
  const MainApp() : super(host: 'localhost', port: 8080);

  @override
  DefaultResponses get defaultResponses => DefaultResponses(
        notFound: SimpleResponse(404, body: {'error': 'not_found'}),
        internalServerError: SimpleResponse(
          500,
          body: 'Something went wrong. Please try again later.',
        ),
      );
}

Any response you don't set keeps its default:

SimpleResponse(statusCode, {headers, body}) takes the status code as a positional argument. A Map or List body is sent as JSON, and a String body as plain text.

In debug mode, error bodies also include a __DEBUG__ block with the exception and stack trace. Profile and release builds leave it out.

HttpError#

Throw an HttpError to send a stable, machine-readable code along with the status. Two different 404s (an unknown user and an unknown organization) then look different to the caller:

import 'package:revali_router/revali_router.dart';

@Controller('users')
class UserController {
  const UserController(this._users);

  final UserService _users;

  @Get(':id')
  Future<User> get(@Param() String id) async {
    final user = await _users.find(id);

    if (user == null) {
      throw HttpError.notFound(
        code: 'user_not_found',
        message: 'No user with id $id',
        details: {'id': id},
      );
    }

    return user;
  }
}

The response keeps the status, and the body is wrapped in error, the same way successful responses are wrapped in data:

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

Every constructor is const.

The error body is a fallback. Exception catchers run first, so a catcher registered for HttpError, or for a subtype of it, can send any shape it likes.

Reading It with revali_client#

A generated revali_client throws ServerException for any response that isn't 2xx:

try {
  await client.users.get(id: '1');
} on ServerException catch (e) {
  if (e.isStructured && e.code == 'user_not_found') return null;
  rethrow;
}

A body that isn't in the error shape (plain text, an HTML error page, another API's format) never throws a parse error. It leaves code, reason and details as null.