FORK FROM BOOM
HTTP-friendly error objects
Lead Maintainer: Adam Bretz
- Boom
- Helper Methods
- HTTP 4xx Errors
Boom.badRequest([message], [data])
Boom.unauthorized([message], [scheme], [attributes])
Boom.paymentRequired([message], [data])
Boom.forbidden([message], [data])
Boom.notFound([message], [data])
Boom.methodNotAllowed([message], [data], [allow])
Boom.notAcceptable([message], [data])
Boom.proxyAuthRequired([message], [data])
Boom.clientTimeout([message], [data])
Boom.conflict([message], [data])
Boom.resourceGone([message], [data])
Boom.lengthRequired([message], [data])
Boom.preconditionFailed([message], [data])
Boom.entityTooLarge([message], [data])
Boom.uriTooLong([message], [data])
Boom.unsupportedMediaType([message], [data])
Boom.rangeNotSatisfiable([message], [data])
Boom.expectationFailed([message], [data])
Boom.badData([message], [data])
Boom.locked([message], [data])
Boom.preconditionRequired([message], [data])
Boom.tooManyRequests([message], [data])
Boom.illegal([message], [data])
- HTTP 5xx Errors
- F.A.Q.
Boom
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
- iftrue
, indicates this is aBoom
object instance.isServer
- convenience bool indicating status code >= 500.message
- the error message.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 ifreformat()
is called. Any content allowed and by default includes the following content:statusCode
- the HTTP status code, derived fromerror.output.statusCode
.error
- the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived fromstatusCode
.message
- the error message derived fromerror.message
.
- inherited
Error
properties.
The Boom
object also supports the following method:
reformat()
- rebuildserror.output
using the other object properties.
Helper Methods
wrap(error, [statusCode], [message])
Decorates an error with the boom properties where:
error
- the error object to wrap. Iferror
is already a boom object, returns back the same object.statusCode
- optional HTTP status code. Defaults to500
.message
- optional message string. If the error already has a message, it adds the message as a prefix. Defaults to no message.
var error = 'Unexpected input';Boom;
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 toerror.data
property.
var error = Boom;
HTTP 4xx Errors
Boom.badRequest([message], [data])
Returns a 400 Bad Request error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.unauthorized([message], [scheme], [attributes])
Returns a 401 Unauthorized error where:
message
- optional message.scheme
can be one of the following:- an authentication scheme name
- 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 whenscheme
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 theattributes
key.null
andundefined
will be replaced with an empty string. Ifattributes
is set,message
will be used as the 'error' segment of the 'WWW-Authenticate' header. Ifmessage
is unset, the 'error' segment of the header will not be present andisMissing
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.
Boom;
Generates the following response:
"payload": ,"headers"
Boom;
Generates the following response:
"payload": ,"headers"
Boom;
Generates the following response:
"payload": ,"headers"
Boom.paymentRequired([message], [data])
Returns a 402 Payment Required error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.forbidden([message], [data])
Returns a 403 Forbidden error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.notFound([message], [data])
Returns a 404 Not Found error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.methodNotAllowed([message], [data], [allow])
Returns a 405 Method Not Allowed error where:
message
- optional message.data
- optional additional error data.allow
- optional string or array of strings (to be combined and separated by ', ') which is set to the 'Allow' header.
Boom;
Generates the following response payload:
Boom.notAcceptable([message], [data])
Returns a 406 Not Acceptable error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.proxyAuthRequired([message], [data])
Returns a 407 Proxy Authentication Required error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.clientTimeout([message], [data])
Returns a 408 Request Time-out error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.conflict([message], [data])
Returns a 409 Conflict error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.resourceGone([message], [data])
Returns a 410 Gone error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.lengthRequired([message], [data])
Returns a 411 Length Required error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.preconditionFailed([message], [data])
Returns a 412 Precondition Failed error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.entityTooLarge([message], [data])
Returns a 413 Request Entity Too Large error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.uriTooLong([message], [data])
Returns a 414 Request-URI Too Large error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.unsupportedMediaType([message], [data])
Returns a 415 Unsupported Media Type error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.rangeNotSatisfiable([message], [data])
Returns a 416 Requested Range Not Satisfiable error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.expectationFailed([message], [data])
Returns a 417 Expectation Failed error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.badData([message], [data])
Returns a 422 Unprocessable Entity error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.locked([message], [data])
Returns a 423 Locked error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.preconditionRequired([message], [data])
Returns a 428 Precondition Required error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.tooManyRequests([message], [data])
Returns a 429 Too Many Requests error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.illegal([message], [data])
Returns a 451 Unavailable For Legal Reasons error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
HTTP 5xx Errors
All 500 errors hide your message from the end user. Your message is recorded in the server log.
Boom.badImplementation([message], [data])
- (alias: internal
)
Returns a 500 Internal Server Error error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.notImplemented([message], [data])
Returns a 501 Not Implemented error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.badGateway([message], [data])
Returns a 502 Bad Gateway error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.serverUnavailable([message], [data])
Returns a 503 Service Unavailable error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
Boom.gatewayTimeout([message], [data])
Returns a 504 Gateway Time-out error where:
message
- optional message.data
- optional additional error data.
Boom;
Generates the following response payload:
F.A.Q.
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.