boom provides a set of utilities for returning HTTP errors. Each utility returns a Boom
error response object which includes the following properties:
isBoom - if true, indicates this is a Boom object instance. Note that this boolean should
only be used if the error is an instance of Error. If it is not certain, use Boom.isBoom()
instead.
isServer - convenience bool indicating status code >= 500.
message - the error message.
typeof - the constructor 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(debug)
Rebuilds error.output using the other object properties where:
debug - a Boolean that, when true, causes Internal Server Error messages to be left in tact. Defaults to false, meaning that Internal Server Error messages are redacted.
Note that Boom object will return true when used with instanceof Boom, but do not use the
Boom prototype (they are either plain Error or the error prototype passed in). This means
Boom objects should only be tested using instanceof Boom or Boom.isBoom() but not by looking
at the prototype or contructor information. This limitation is to avoid manipulating the prototype
chain which is very slow.
Helper Methods
new Boom(message, [options])
Creates a new Boom object using the provided message and then calling
boomify() to decorate the error with the Boom properties, where:
message - the error message. If message is an error, it is the same as calling
boomify() directly.
options - and optional object where:
statusCode - the HTTP status code. Defaults to 500 if no status code is already set.
data - additional error information (assigned to error.data).
decorate - an option with extra properties to set on the error object.
ctor - constructor reference used to crop the exception call stack output.
if message is an error object, also supports the other boomify()
options.
boomify(err, [options])
Decorates an error with the Boom properties where:
err - 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 and err is not a Boom object.
message - error message string. If the error already has a message, the provided message is added as a prefix.
Defaults to no message.
decorate - an option with extra properties to set on the error object.
override - if false, the err 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).
var error = new Error('Unexpected input');Boom.boomify(error, { statusCode: 400 });
isBoom(err)
Identifies whether an error is a Boom object. Same as calling instanceof Boom.
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.