@hapi/boom

A Boom error object contains several useful properties for both application logic and generating HTTP responses:

• isBoom: Boolean indicating if the object is a Boom instance.
• isServer: Boolean indicating if the status code is $\ge 500$.
• data: Custom data object passed during creation.
• message: The error message string.
• output: An object containing the formatted response structure:
  • output.statusCode: The HTTP status code.
  • output.headers: An object containing HTTP headers.
  • output.payload: The formatted response body (containing statusCode, error, and message).
• reformat(debug?: boolean): Returns a string representation of the error. If debug is true, it does not hide the original 500 error message.

The Boom class can be instantiated directly to create custom error objects. You can provide a message or an existing Error object.

Options:

• statusCode (number): The HTTP status code (defaults to 500).
• data (any): Additional data to attach to the error.
• ctor (function): The constructor function to use for stack trace filtering (defaults to the specific factory function).
• decorate (object): An object containing properties to be assigned to the error instance.

If an Error instance is passed as the first argument, boomify() is used internally to wrap it.

Boom provides factory functions for common 4xx HTTP errors. Most functions accept an optional messageOrError (string or Error) and optional data (custom metadata).

Common 4xx functions include:

• badRequest(messageOrError, data) (400)
• unauthorized(messageOrError) (401)
• forbidden(messageOrError, data) (403)
• notFound(messageOrError, data) (404)
• methodNotAllowed(messageOrError, data, allow) (405)
• conflict(messageOrError, data) (409)
• entityTooLarge(messageOrError, data) (413)
• tooManyRequests(messageOrError, data) (429)
• badData(messageOrError, data) (422)

The unauthorized() function can be used to provide specific details for 401 responses, such as the authentication scheme or WWW-Authenticate headers.

• With scheme and attributes: unauthorized(message, scheme, attributes)
• With WWW-Authenticate header: unauthorized(message, wwwAuthenticateArray)

If you provide a scheme and attributes, the error will include an isMissing property indicating if credentials were missing versus invalid.

Use isBoom(err, statusCode) to verify if an object is a Boom error. You can optionally provide a statusCode to check if the error matches a specific HTTP status.

Returns true if the error is an instance of Error, has the isBoom property, and matches the provided statusCode (if one was given).

Boom provides factory functions for common 5xx HTTP errors. These are typically used to indicate server-side failures.

Common 5xx functions include:

• internal(messageOrError, data, statusCode) (500 - allows status code override)
• badImplementation(messageOrError, data) (500)
• notImplemented(messageOrError, data) (501)
• badGateway(messageOrError, data) (502)
• serverUnavailable(messageOrError, data) (503)
• gatewayTimeout(messageOrError, data) (504)

Boom provides factory functions for common 5xx server errors.

Common 5xx Factories:

• internal(message, data, statusCode) (500) — allows custom status code.
• notImplemented(message, data) (501)
• badGateway(message, data) (502)
• serverUnavailable(message, data) (503)
• gatewayTimeout(message, data) (504)
• badImplementation(message, data) (500) — sets isDeveloperError: true.

Note on 500 errors: By default, Boom hides the actual error message in the output.payload.message for 500 errors (replacing it with 'An internal server error occurred') to prevent leaking sensitive information, unless debug mode is enabled during reformatting.

Use boomify(err, options) to convert a standard JavaScript Error into a Boom error. This is useful for catching generic errors and converting them into structured HTTP errors.

Options:

• data (any): Data to attach to the error.
• decorate (object): Properties to assign to the error.
• statusCode (number): The HTTP status code to apply.
• message (string): A custom message to apply.
• override (boolean): If false, the function will return the original error if it is already a Boom error and no new status/message is provided (defaults to true).