api.service.HttpException

This custom exception class is provided for simplifying error handling in code involved in handling an HTTP request.

Usage Example

Let's assume a controller component like this one:

export default function() {
	const api = this;
	const { service } = api;

	const logError = api.log( "my-app:custom:error" );

	class MyCustomController {
		static someEndpoint( req, res ) {
			if ( req.params.foo !== "expected" ) {
				throw new service.HttpException( 400, "invalid parameter" );
			}

			if ( req.query.id !== "john.doe" ) {
				throw new service.HttpException( 403, "access forbidden" );
			}

			// TODO provide response
			// this code might crash unexpectedly ...
		}
	}
}

The default request dispatcher of Hitchy is invoking the controller and delegates any captured exception to some fallback controller used to generically rendering error responses. That response is provided in one of a few supported formats matching the client's Accept request header.

Inheritance

This class inherits from native Javascript class Error.

Constructor

An exception is created with a status code and an error message. The former is used as HTTP status code on responding to the client. The latter is provided in body of response.

throw new api.service.HttpException( 400, "malformed id" );

The status code is optional and defaults to 500.

throw new api.service.HttpException( "missing database" );

Properties

statusCode

Exposes the numeric HTTP status code associated with the exception.

Methods

withContent()

Attaches custom content to be used as response to some client's request instead of the default.

The method is invoked with the custom content and its optional MIME type. The latter is optional: if omitted, the default MIME type if application/json for any truthy object or text/plain for any other content converted to a string.

For daisy-chaining calls right on creating and throwing an exception, the method is returning current exception:

throw new api.service.HttpException( 401, "malformed id" )
    .withContent( {
        error: "malformed id",
        reason: "parameter",
        culprit: "id",
    } );

The method can be invoked multiple times e.g. to provide custom responses for different MIME types accepted by the client:

throw new api.service.HttpException( 401, "ID has been rejected due to containing letters" )
    .withContent( "malformed ID" )
    .withContent( `<b>Error:</b> ID is malformed (<a href="#malformedId">Help</a>)`, 'text/html' )
    .withContent( {
        error: "malformed id",
        reason: "parameter",
        culprit: "id",
    } );

respondToRequest()

This method is invoked by Response when rendering a response after catching an exception thrown during dispatching an incoming HTTP request. The method is invoked with the request descriptor and the response manager as arguments. It must return true after having described a custom response using provided response manager. Otherwise, the fallback of Response is used.

By default, this method is checking custom content attached to the exception using withContent() and delivers any such content matching current request's Accept header. If neither variant is matching, false is returned.