1 ![boom Logo](https://raw.github.com/hapijs/boom/master/images/boom.png)
3 HTTP-friendly error objects
5 [![Build Status](https://secure.travis-ci.org/hapijs/boom.png)](http://travis-ci.org/hapijs/boom)
6 [![Current Version](https://img.shields.io/npm/v/boom.svg)](https://www.npmjs.com/package/boom)
8 Lead Maintainer: [Adam Bretz](https://github.com/arb)
10 **boom** provides a set of utilities for returning HTTP errors. Each utility returns a `Boom` error response
11 object (instance of `Error`) which includes the following properties:
12 - `isBoom` - if `true`, indicates this is a `Boom` object instance.
13 - `isServer` - convenience bool indicating status code >= 500.
14 - `message` - the error message.
15 - `output` - the formatted response. Can be directly manipulated after object construction to return a custom
16 error response. Allowed root keys:
17 - `statusCode` - the HTTP status code (typically 4xx or 5xx).
18 - `headers` - an object containing any HTTP headers where each key is a header name and value is the header content.
19 - `payload` - the formatted object used as the response payload (stringified). Can be directly manipulated but any
21 if `reformat()` is called. Any content allowed and by default includes the following content:
22 - `statusCode` - the HTTP status code, derived from `error.output.statusCode`.
23 - `error` - the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived from `statusCode`.
24 - `message` - the error message derived from `error.message`.
25 - inherited `Error` properties.
27 The `Boom` object also supports the following method:
28 - `reformat()` - rebuilds `error.output` using the other object properties.
33 - [`wrap(error, [statusCode], [message])`](#wraperror-statuscode-message)
34 - [`create(statusCode, [message], [data])`](#createstatuscode-message-data)
36 - 400: [`Boom.badRequest([message], [data])`](#boombadrequestmessage-data)
37 - 401: [`Boom.unauthorized([message], [scheme], [attributes])`](#boomunauthorizedmessage-scheme-attributes)
38 - 403: [`Boom.forbidden([message], [data])`](#boomforbiddenmessage-data)
39 - 404: [`Boom.notFound([message], [data])`](#boomnotfoundmessage-data)
40 - 405: [`Boom.methodNotAllowed([message], [data])`](#boommethodnotallowedmessage-data)
41 - 406: [`Boom.notAcceptable([message], [data])`](#boomnotacceptablemessage-data)
42 - 407: [`Boom.proxyAuthRequired([message], [data])`](#boomproxyauthrequiredmessage-data)
43 - 408: [`Boom.clientTimeout([message], [data])`](#boomclienttimeoutmessage-data)
44 - 409: [`Boom.conflict([message], [data])`](#boomconflictmessage-data)
45 - 410: [`Boom.resourceGone([message], [data])`](#boomresourcegonemessage-data)
46 - 411: [`Boom.lengthRequired([message], [data])`](#boomlengthrequiredmessage-data)
47 - 412: [`Boom.preconditionFailed([message], [data])`](#boompreconditionfailedmessage-data)
48 - 413: [`Boom.entityTooLarge([message], [data])`](#boomentitytoolargemessage-data)
49 - 414: [`Boom.uriTooLong([message], [data])`](#boomuritoolongmessage-data)
50 - 415: [`Boom.unsupportedMediaType([message], [data])`](#boomunsupportedmediatypemessage-data)
51 - 416: [`Boom.rangeNotSatisfiable([message], [data])`](#boomrangenotsatisfiablemessage-data)
52 - 417: [`Boom.expectationFailed([message], [data])`](#boomexpectationfailedmessage-data)
53 - 422: [`Boom.badData([message], [data])`](#boombaddatamessage-data)
54 - 428: [`Boom.preconditionRequired([message], [data])`](#boompreconditionrequiredmessage-data)
55 - 429: [`Boom.tooManyRequests([message], [data])`](#boomtoomanyrequestsmessage-data)
57 - 500: [`Boom.badImplementation([message], [data])`](#boombadimplementationmessage-data)
58 - 501: [`Boom.notImplemented([message], [data])`](#boomnotimplementedmessage-data)
59 - 502: [`Boom.badGateway([message], [data])`](#boombadgatewaymessage-data)
60 - 503: [`Boom.serverTimeout([message], [data])`](#boomservertimeoutmessage-data)
61 - 504: [`Boom.gatewayTimeout([message], [data])`](#boomgatewaytimeoutmessage-data)
67 ### `wrap(error, [statusCode], [message])`
69 Decorates an error with the **boom** properties where:
70 - `error` - the error object to wrap. If `error` is already a **boom** object, returns back the same object.
71 - `statusCode` - optional HTTP status code. Defaults to `500`.
72 - `message` - optional message string. If the error already has a message, it adds the message as a prefix.
73 Defaults to no message.
76 var error = new Error('Unexpected input');
77 Boom.wrap(error, 400);
80 ### `create(statusCode, [message], [data])`
82 Generates an `Error` object with the **boom** decorations where:
83 - `statusCode` - an HTTP error code number. Must be greater or equal 400.
84 - `message` - optional message string.
85 - `data` - additional error data set to `error.data` property.
88 var error = Boom.create(400, 'Bad request', { timestamp: Date.now() });
93 ### `Boom.badRequest([message], [data])`
95 Returns a 400 Bad Request error where:
96 - `message` - optional message.
97 - `data` - optional additional error data.
100 Boom.badRequest('invalid query');
103 Generates the following response payload:
108 "error": "Bad Request",
109 "message": "invalid query"
113 ### `Boom.unauthorized([message], [scheme], [attributes])`
115 Returns a 401 Unauthorized error where:
116 - `message` - optional message.
117 - `scheme` can be one of the following:
118 - an authentication scheme name
119 - an array of string values. These values will be separated by ', ' and set to the 'WWW-Authenticate' header.
120 - `attributes` - an object of values to use while setting the 'WWW-Authenticate' header. This value is only used
121 when `schema` is a string, otherwise it is ignored. Every key/value pair will be included in the
122 'WWW-Authenticate' in the format of 'key="value"' as well as in the response payload under the `attributes` key.
123 `null` and `undefined` will be replaced with an empty string. If `attributes` is set, `message` will be used as
124 the 'error' segment of the 'WWW-Authenticate' header. If `message` is unset, the 'error' segment of the header
125 will not be present and `isMissing` will be true on the error object.
127 If either `scheme` or `attributes` are set, the resultant `Boom` object will have the 'WWW-Authenticate' header set for the response.
130 Boom.unauthorized('invalid password');
133 Generates the following response:
138 "error": "Unauthorized",
139 "message": "invalid password"
145 Boom.unauthorized('invalid password', 'sample');
148 Generates the following response:
153 "error": "Unauthorized",
154 "message": "invalid password",
156 "error": "invalid password"
160 "WWW-Authenticate": "sample error=\"invalid password\""
165 Boom.unauthorized('invalid password', 'sample', { ttl: 0, cache: null, foo: 'bar' });
168 Generates the following response:
173 "error": "Unauthorized",
174 "message": "invalid password",
176 "error": "invalid password",
183 "WWW-Authenticate": "sample ttl=\"0\", cache=\"\", foo=\"bar\", error=\"invalid password\""
187 ### `Boom.forbidden([message], [data])`
189 Returns a 403 Forbidden error where:
190 - `message` - optional message.
191 - `data` - optional additional error data.
194 Boom.forbidden('try again some time');
197 Generates the following response payload:
202 "error": "Forbidden",
203 "message": "try again some time"
207 ### `Boom.notFound([message], [data])`
209 Returns a 404 Not Found error where:
210 - `message` - optional message.
211 - `data` - optional additional error data.
214 Boom.notFound('missing');
217 Generates the following response payload:
222 "error": "Not Found",
227 ### `Boom.methodNotAllowed([message], [data])`
229 Returns a 405 Method Not Allowed error where:
230 - `message` - optional message.
231 - `data` - optional additional error data.
234 Boom.methodNotAllowed('that method is not allowed');
237 Generates the following response payload:
242 "error": "Method Not Allowed",
243 "message": "that method is not allowed"
247 ### `Boom.notAcceptable([message], [data])`
249 Returns a 406 Not Acceptable error where:
250 - `message` - optional message.
251 - `data` - optional additional error data.
254 Boom.notAcceptable('unacceptable');
257 Generates the following response payload:
262 "error": "Not Acceptable",
263 "message": "unacceptable"
267 ### `Boom.proxyAuthRequired([message], [data])`
269 Returns a 407 Proxy Authentication Required error where:
270 - `message` - optional message.
271 - `data` - optional additional error data.
274 Boom.proxyAuthRequired('auth missing');
277 Generates the following response payload:
282 "error": "Proxy Authentication Required",
283 "message": "auth missing"
287 ### `Boom.clientTimeout([message], [data])`
289 Returns a 408 Request Time-out error where:
290 - `message` - optional message.
291 - `data` - optional additional error data.
294 Boom.clientTimeout('timed out');
297 Generates the following response payload:
302 "error": "Request Time-out",
303 "message": "timed out"
307 ### `Boom.conflict([message], [data])`
309 Returns a 409 Conflict error where:
310 - `message` - optional message.
311 - `data` - optional additional error data.
314 Boom.conflict('there was a conflict');
317 Generates the following response payload:
323 "message": "there was a conflict"
327 ### `Boom.resourceGone([message], [data])`
329 Returns a 410 Gone error where:
330 - `message` - optional message.
331 - `data` - optional additional error data.
334 Boom.resourceGone('it is gone');
337 Generates the following response payload:
343 "message": "it is gone"
347 ### `Boom.lengthRequired([message], [data])`
349 Returns a 411 Length Required error where:
350 - `message` - optional message.
351 - `data` - optional additional error data.
354 Boom.lengthRequired('length needed');
357 Generates the following response payload:
362 "error": "Length Required",
363 "message": "length needed"
367 ### `Boom.preconditionFailed([message], [data])`
369 Returns a 412 Precondition Failed error where:
370 - `message` - optional message.
371 - `data` - optional additional error data.
374 Boom.preconditionFailed();
377 Generates the following response payload:
382 "error": "Precondition Failed"
386 ### `Boom.entityTooLarge([message], [data])`
388 Returns a 413 Request Entity Too Large error where:
389 - `message` - optional message.
390 - `data` - optional additional error data.
393 Boom.entityTooLarge('too big');
396 Generates the following response payload:
401 "error": "Request Entity Too Large",
406 ### `Boom.uriTooLong([message], [data])`
408 Returns a 414 Request-URI Too Large error where:
409 - `message` - optional message.
410 - `data` - optional additional error data.
413 Boom.uriTooLong('uri is too long');
416 Generates the following response payload:
421 "error": "Request-URI Too Large",
422 "message": "uri is too long"
426 ### `Boom.unsupportedMediaType([message], [data])`
428 Returns a 415 Unsupported Media Type error where:
429 - `message` - optional message.
430 - `data` - optional additional error data.
433 Boom.unsupportedMediaType('that media is not supported');
436 Generates the following response payload:
441 "error": "Unsupported Media Type",
442 "message": "that media is not supported"
446 ### `Boom.rangeNotSatisfiable([message], [data])`
448 Returns a 416 Requested Range Not Satisfiable error where:
449 - `message` - optional message.
450 - `data` - optional additional error data.
453 Boom.rangeNotSatisfiable();
456 Generates the following response payload:
461 "error": "Requested Range Not Satisfiable"
465 ### `Boom.expectationFailed([message], [data])`
467 Returns a 417 Expectation Failed error where:
468 - `message` - optional message.
469 - `data` - optional additional error data.
472 Boom.expectationFailed('expected this to work');
475 Generates the following response payload:
480 "error": "Expectation Failed",
481 "message": "expected this to work"
485 ### `Boom.badData([message], [data])`
487 Returns a 422 Unprocessable Entity error where:
488 - `message` - optional message.
489 - `data` - optional additional error data.
492 Boom.badData('your data is bad and you should feel bad');
495 Generates the following response payload:
500 "error": "Unprocessable Entity",
501 "message": "your data is bad and you should feel bad"
505 ### `Boom.preconditionRequired([message], [data])`
507 Returns a 428 Precondition Required error where:
508 - `message` - optional message.
509 - `data` - optional additional error data.
512 Boom.preconditionRequired('you must supply an If-Match header');
515 Generates the following response payload:
520 "error": "Precondition Required",
521 "message": "you must supply an If-Match header"
525 ### `Boom.tooManyRequests([message], [data])`
527 Returns a 429 Too Many Requests error where:
528 - `message` - optional message.
529 - `data` - optional additional error data.
532 Boom.tooManyRequests('you have exceeded your request limit');
535 Generates the following response payload:
540 "error": "Too Many Requests",
541 "message": "you have exceeded your request limit"
547 All 500 errors hide your message from the end user. Your message is recorded in the server log.
549 ### `Boom.badImplementation([message], [data])`
551 Returns a 500 Internal Server Error error where:
552 - `message` - optional message.
553 - `data` - optional additional error data.
556 Boom.badImplementation('terrible implementation');
559 Generates the following response payload:
564 "error": "Internal Server Error",
565 "message": "An internal server error occurred"
569 ### `Boom.notImplemented([message], [data])`
571 Returns a 501 Not Implemented error where:
572 - `message` - optional message.
573 - `data` - optional additional error data.
576 Boom.notImplemented('method not implemented');
579 Generates the following response payload:
584 "error": "Not Implemented",
585 "message": "method not implemented"
589 ### `Boom.badGateway([message], [data])`
591 Returns a 502 Bad Gateway error where:
592 - `message` - optional message.
593 - `data` - optional additional error data.
596 Boom.badGateway('that is a bad gateway');
599 Generates the following response payload:
604 "error": "Bad Gateway",
605 "message": "that is a bad gateway"
609 ### `Boom.serverTimeout([message], [data])`
611 Returns a 503 Service Unavailable error where:
612 - `message` - optional message.
613 - `data` - optional additional error data.
616 Boom.serverTimeout('unavailable');
619 Generates the following response payload:
624 "error": "Service Unavailable",
625 "message": "unavailable"
629 ### `Boom.gatewayTimeout([message], [data])`
631 Returns a 504 Gateway Time-out error where:
632 - `message` - optional message.
633 - `data` - optional additional error data.
636 Boom.gatewayTimeout();
639 Generates the following response payload:
644 "error": "Gateway Time-out"
650 ###### How do I include extra information in my responses? `output.payload` is missing `data`, what gives?
652 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"](https://github.com/hapijs/hapi/blob/master/API.md#error-transformation) section in the hapi documentation.