boom provides a set of utilities for returning HTTP errors. Each utility returns a Boom error response
object (instance of Error) which includes the following properties:
isBoom - if true, indicates this is a Boom object instance.
isServer - convenience bool indicating status code >= 500.
message - the error message.
typeof - the contructor used to create the error (e.g. Boom.badRequest).
output - the formatted response. Can be directly manipulated after object construction to return a custom
error response. Allowed root keys:
statusCode - the HTTP status code (typically 4xx or 5xx).
headers - an object containing any HTTP headers where each key is a header name and value is the header content.
payload - the formatted object used as the response payload (stringified). Can be directly manipulated but any
changes will be lost
if reformat() is called. Any content allowed and by default includes the following content:
statusCode - the HTTP status code, derived from error.output.statusCode.
error - the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived from statusCode.
message - the error message derived from error.message.
inherited Error properties.
The Boom object also supports the following method:
reformat() - rebuilds error.output using the other object properties.
Helper Methods
boomify(error, [options])
Decorates an error with the boom properties where:
error - the Error object to decorate.
options - optional object with the following optional settings:
statusCode - the HTTP status code. Defaults to 500 if no status code is already set.
message - error message string. If the error already has a message, the provided message is added as a prefix.
Defaults to no message.
override - if false, the error provided is a boom object, and a statusCode or message are provided,
the values are ignored. Defaults to true (apply the provided statusCode and message options to the error
regardless of its type, Error or boom object).
Note: This method replaces the wrap() and changes the default behavior to override
existing boom objects with the provided status code and message.
var error = new Error('Unexpected input');Boom.boomify(error, { statusCode: 400 });
wrap(error, [statusCode], [message])
Note: This method is deprecated.
Decorates an error with the boom properties where:
error - the error object to wrap. If error is already a boom object, returns back the same object.
statusCode - optional HTTP status code. Defaults to 500.
message - optional message string. If the error already has a message, it adds the message as a prefix.
Defaults to no message.
var error = new Error('Unexpected input');Boom.wrap(error, 400);
create(statusCode, [message], [data])
Generates an Error object with the boom decorations where:
statusCode - an HTTP error code number. Must be greater or equal 400.
message - optional message string.
data - additional error data set to error.data property.
var error = Boom.create(400, 'Bad request', { timestamp: Date.now() });
an array of string values. These values will be separated by ', ' and set to the 'WWW-Authenticate' header.
attributes - an object of values to use while setting the 'WWW-Authenticate' header. This value is only used
when scheme is a string, otherwise it is ignored. Every key/value pair will be included in the
'WWW-Authenticate' in the format of 'key="value"' as well as in the response payload under the attributes key. Alternatively value can be a string which is use to set the value of the scheme, for example setting the token value for negotiate header. If string is used message parameter must be null.
null and undefined will be replaced with an empty string. If attributes is set, message will be used as
the 'error' segment of the 'WWW-Authenticate' header. If message is unset, the 'error' segment of the header
will not be present and isMissing will be true on the error object.
If either scheme or attributes are set, the resultant Boom object will have the 'WWW-Authenticate' header set for the response.
Q How do I include extra information in my responses? output.payload is missing data, what gives?
A There is a reason the values passed back in the response payloads are pretty locked down. It's mostly for security and to not leak any important information back to the client. This means you will need to put in a little more effort to include extra information about your custom error. Check out the "Error transformation" section in the hapi documentation.