Skip to main content
Version: 0.3

Error handlers

Marten provides default error handlers that you can leverage to show specific error conditions to your users: when a page is not found, when an operation is forbidden, in case of a server error, etc.

The default error handlers

Marten provides default error handlers for the following situations:

  • when a record or a route is not found, it will return a default Page Not Found (404) response
  • when an unexpected error occurs, it will return a default Internal Server Error (500) response
  • when a suspicious operation is detected, it will return a default Bad Request (400) response
  • when an action is forbidden, it will return a default Forbidden (403) response

Note that you don't need to manually interact with these default error handlers: they are automatically used by the Marten server when the above error conditions are met.

Page Not Found (404)

A Page Not Found (404) response is automatically returned by the Marten::Handlers::Defaults::PageNotFound handler when:

info

If your project is running in debug mode, Marten will automatically show a different page containing specific information about the original request instead of using the default Page Not Found handler.

Internal Server Error (500)

An Internal Server Error (500) response is automatically returned by the Marten::Handlers::Defaults::ServerError handler when an unhandled exception is intercepted by the Marten server.

info

If your project is running in debug mode, Marten will automatically show a different page containing specific information about the error that occurred (traceback, request details, etc) instead of using the default Internal Server Error handler.

Bad Request (400)

A Bad Request (400) response is automatically returned by the Marten::Handlers::Defaults::BadRequest handler when the Marten::HTTP::Errors::SuspiciousOperation exception is raised.

Forbidden (403)

A Forbidden (403) response is automatically returned by the Marten::Handlers::Defaults::PermissionDenied handler when the Marten::HTTP::Errors::PermissionDenied exception is raised.

Customizing error handlers

Each of the error handlers mentioned above can be easily customized: by default they provide a "raw" server response with a standard message, and it might make sense on a project basis to customize how they show up to your users. As such, each handler is associated with a dedicated template name that will be rendered if your project defines it. Each of these handlers can also be replaced by a custom one by using the appropriate settings.

These customization options are listed below:

ErrorTemplate nameHandler setting
Page Not Found (404)404.htmlhandler404
Internal Server Error (500)500.htmlhandler500
Bad Request (400)400.htmlhandler400
Forbidden (403)403.htmlhandler403

For example, you could define a default "Page Not Found" template by defining a 404.html HTML template file in your project's templates folder.