These libraries assist Node.js developers in managing HTTP response statuses and error objects. boom, create-error, and http-errors focus on generating structured error instances, often with HTTP status codes attached. http-status and http-status-codes provide constant values and descriptions for standard HTTP status codes, helping to avoid magic numbers in code. Together, they cover the spectrum from defining status constants to throwing properly formatted errors in server-side applications.
Building robust server-side applications requires clear communication between the server and client. When something goes wrong, sending the right HTTP status code and a structured error message is critical. The packages boom, create-error, http-errors, http-status, and http-status-codes all aim to solve parts of this problem, but they serve different roles. Some create error objects, while others simply provide constants for status codes.
Let's break down how they differ and when to use each one.
When an API request fails, you need to throw an error that your framework can catch and convert into an HTTP response. These three packages handle that differently.
http-errors: The Express Standardhttp-errors is the go-to choice for Express and Koa applications. It creates error objects that have a status property, which middleware like express.errorHandler automatically reads to set the response code.
// http-errors usage
const createError = require('http-errors');
// Throw a 404 error with a custom message
throw createError(404, 'User not found');
// Or use a named constructor
throw createError.NotFound('User not found');
boom: The Legacy hapi Choiceboom was the standard for the hapi framework. It wraps errors with HTTP status information. However, the unscoped boom package is now considered legacy. The active version is @hapi/boom. If you see boom in a modern codebase, it is likely outdated.
// boom usage (Legacy)
const Boom = require('boom');
// Throw a 404 error
throw Boom.notFound('User not found');
// Throw a 500 error with custom data
throw Boom.badImplementation('Database failure', { details: 'Connection timeout' });
create-error: Custom Classes Without HTTP Logiccreate-error does not assume you are working with HTTP. It helps you create custom error constructors quickly. You would use this if you need specific error types for business logic (e.g., PaymentError) that might later be mapped to HTTP statuses manually.
// create-error usage
const createError = require('create-error');
// Define a custom error type
const PaymentError = createError('PaymentError');
// Throw the custom error
throw new PaymentError('Card declined', { code: 'CARD_DECLINED' });
Hardcoding numbers like 404 or 500 makes code harder to read. These packages provide named constants like NOT_FOUND or INTERNAL_SERVER_ERROR.
http-status: Simple Numeric Mappinghttp-status provides a straightforward map of status names to numbers. It is lightweight and good if you just need the number.
// http-status usage
const httpStatus = require('http-status');
// Access status code by name
const code = httpStatus.NOT_FOUND; // 404
// Use in a response
res.status(httpStatus.CREATED).send('Resource created');
http-status-codes: Detailed Metadatahttp-status-codes offers more than just numbers. It includes reason phrases (e.g., 'Not Found') and categorization. It is often more maintained and provides reverse lookups (number to name).
// http-status-codes usage
const StatusCodes = require('http-status-codes');
// Access status code
const code = StatusCodes.NOT_FOUND; // 404
// Access reason phrase
const phrase = StatusCodes.getStatusText(404); // 'Not Found'
// Use in a response
res.status(StatusCodes.CREATED).send('Resource created');
Maintenance status is a critical factor when choosing infrastructure libraries.
boom: The unscoped boom package is deprecated. The hapi team moved to scoped packages (@hapi/boom) several versions ago. Using the old boom puts you at risk of missing security patches. Do not use boom in new projects.create-error: This package is stable but sees infrequent updates. Since ES6 classes are now standard in Node.js, you can often achieve the same result with native class extension without a dependency.http-errors: Actively maintained and widely adopted. It is safe for production use in Express/Koa ecosystems.http-status vs http-status-codes: Both are stable, but http-status-codes tends to have more frequent updates regarding new or rare status codes and includes more helper methods.You are building a REST API with Express. You need to validate input and return 400 errors, or return 404 if a resource is missing.
http-errors// Express + http-errors
app.get('/users/:id', async (req, res, next) => {
const user = await db.findUser(req.params.id);
if (!user) {
return next(createError(404, 'User not found'));
}
res.json(user);
});
You are working on an older hapi v16 application that is scheduled for migration next year.
boom (Legacy)// Legacy hapi + boom
server.route({
method: 'GET',
path: '/items/{id}',
handler: async (request, h) => {
const item = await getItem(request.params.id);
if (!item) {
throw Boom.notFound();
}
return item;
}
});
You are building a core logic layer that is framework-agnostic. You want to throw errors that describe business problems, not HTTP codes.
create-error// Domain Logic + create-error
const InventoryError = createError('InventoryError');
function reserveStock(item, qty) {
if (stock < qty) {
throw new InventoryError('Insufficient stock');
}
}
You need to display the text reason for a status code in a dashboard admin panel (e.g., showing "404 - Not Found" in a log viewer).
http-status-codesgetStatusText() and other metadata utilities out of the box.// Admin Dashboard + http-status-codes
function renderStatusLog(logs) {
return logs.map(log => {
const text = StatusCodes.getStatusText(log.code);
return `${log.code} - ${text}`;
});
}
| Package | Primary Use | HTTP Specific | Maintenance Status | Best For |
|---|---|---|---|---|
boom | Error Objects | β Yes | β Deprecated (Use @hapi/boom) | Legacy hapi apps |
create-error | Custom Classes | β No | β οΈ Stable / Low Activity | Domain logic errors |
http-errors | Error Objects | β Yes | β Active | Express/Koa APIs |
http-status | Status Constants | β Yes | β Active | Simple status codes |
http-status-codes | Status Constants | β Yes | β Active | Detailed status info |
For most modern Node.js backend development, http-errors is the essential choice for handling failures. It ensures your errors carry the right status codes and play nicely with the ecosystem's middleware.
For status codes, http-status-codes is generally superior to http-status due to its richer API and metadata support, though both are acceptable for simple constant mapping.
Avoid boom unless you are strictly maintaining legacy hapi code. For new hapi projects, use @hapi/boom. Finally, consider if you really need create-error; with modern JavaScript, extending the native Error class is often enough for custom error types without adding a dependency.
Choose boom only if you are maintaining a legacy application built on hapi framework v16 or earlier. For all new projects, avoid this package as it has been deprecated in favor of the scoped @hapi/boom. Using the unscoped version may lead to security vulnerabilities or lack of support.
Choose create-error if you need to generate custom error classes that are not strictly tied to HTTP status codes. It is useful for domain-specific errors in backend logic where you want a clean constructor without pulling in HTTP-specific dependencies.
Choose http-errors for most Node.js server applications, especially those using Express or Koa. It is the industry standard for creating HTTP error objects that integrate seamlessly with middleware error handlers, providing both status codes and human-readable messages.
Choose http-status if you need a lightweight set of constants for HTTP status codes and prefer a simple mapping of names to numbers. It is suitable for projects that only need the numeric codes without additional metadata like status messages.
Choose http-status-codes if you require detailed information about status codes, including reason phrases and categories. It is generally more up-to-date and feature-rich than http-status, making it better for validation logic or dynamic status messaging.

HTTP-friendly error objects
Lead Maintainer: Eran Hammer
reformat(debug)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.teapot([message], [data])Boom.badData([message], [data])Boom.locked([message], [data])Boom.failedDependency([message], [data])Boom.preconditionRequired([message], [data])Boom.tooManyRequests([message], [data])Boom.illegal([message], [data])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.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.
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.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.
Boom.badRequest([message], [data])Returns a 400 Bad Request error where:
message - optional message.data - optional additional error data.Boom.badRequest('invalid query');
Generates the following response payload:
{
"statusCode": 400,
"error": "Bad Request",
"message": "invalid query"
}
Boom.unauthorized([message], [scheme], [attributes])Returns a 401 Unauthorized error where:
message - optional message.scheme can be one of the following:
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.
Boom.unauthorized('invalid password');
Generates the following response:
"payload": {
"statusCode": 401,
"error": "Unauthorized",
"message": "invalid password"
},
"headers" {}
Boom.unauthorized('invalid password', 'sample');
Generates the following response:
"payload": {
"statusCode": 401,
"error": "Unauthorized",
"message": "invalid password",
"attributes": {
"error": "invalid password"
}
},
"headers" {
"WWW-Authenticate": "sample error=\"invalid password\""
}
Boom.unauthorized(null, 'Negotiate', 'VGhpcyBpcyBhIHRlc3QgdG9rZW4=');
Generates the following response:
"payload": {
"statusCode": 401,
"error": "Unauthorized",
"attributes": "VGhpcyBpcyBhIHRlc3QgdG9rZW4="
},
"headers" {
"WWW-Authenticate": "Negotiate VGhpcyBpcyBhIHRlc3QgdG9rZW4="
}
Boom.unauthorized('invalid password', 'sample', { ttl: 0, cache: null, foo: 'bar' });
Generates the following response:
"payload": {
"statusCode": 401,
"error": "Unauthorized",
"message": "invalid password",
"attributes": {
"error": "invalid password",
"ttl": 0,
"cache": "",
"foo": "bar"
}
},
"headers" {
"WWW-Authenticate": "sample ttl=\"0\", cache=\"\", foo=\"bar\", error=\"invalid password\""
}
Boom.paymentRequired([message], [data])Returns a 402 Payment Required error where:
message - optional message.data - optional additional error data.Boom.paymentRequired('bandwidth used');
Generates the following response payload:
{
"statusCode": 402,
"error": "Payment Required",
"message": "bandwidth used"
}
Boom.forbidden([message], [data])Returns a 403 Forbidden error where:
message - optional message.data - optional additional error data.Boom.forbidden('try again some time');
Generates the following response payload:
{
"statusCode": 403,
"error": "Forbidden",
"message": "try again some time"
}
Boom.notFound([message], [data])Returns a 404 Not Found error where:
message - optional message.data - optional additional error data.Boom.notFound('missing');
Generates the following response payload:
{
"statusCode": 404,
"error": "Not Found",
"message": "missing"
}
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.methodNotAllowed('that method is not allowed');
Generates the following response payload:
{
"statusCode": 405,
"error": "Method Not Allowed",
"message": "that method is not allowed"
}
Boom.notAcceptable([message], [data])Returns a 406 Not Acceptable error where:
message - optional message.data - optional additional error data.Boom.notAcceptable('unacceptable');
Generates the following response payload:
{
"statusCode": 406,
"error": "Not Acceptable",
"message": "unacceptable"
}
Boom.proxyAuthRequired([message], [data])Returns a 407 Proxy Authentication Required error where:
message - optional message.data - optional additional error data.Boom.proxyAuthRequired('auth missing');
Generates the following response payload:
{
"statusCode": 407,
"error": "Proxy Authentication Required",
"message": "auth missing"
}
Boom.clientTimeout([message], [data])Returns a 408 Request Time-out error where:
message - optional message.data - optional additional error data.Boom.clientTimeout('timed out');
Generates the following response payload:
{
"statusCode": 408,
"error": "Request Time-out",
"message": "timed out"
}
Boom.conflict([message], [data])Returns a 409 Conflict error where:
message - optional message.data - optional additional error data.Boom.conflict('there was a conflict');
Generates the following response payload:
{
"statusCode": 409,
"error": "Conflict",
"message": "there was a conflict"
}
Boom.resourceGone([message], [data])Returns a 410 Gone error where:
message - optional message.data - optional additional error data.Boom.resourceGone('it is gone');
Generates the following response payload:
{
"statusCode": 410,
"error": "Gone",
"message": "it is gone"
}
Boom.lengthRequired([message], [data])Returns a 411 Length Required error where:
message - optional message.data - optional additional error data.Boom.lengthRequired('length needed');
Generates the following response payload:
{
"statusCode": 411,
"error": "Length Required",
"message": "length needed"
}
Boom.preconditionFailed([message], [data])Returns a 412 Precondition Failed error where:
message - optional message.data - optional additional error data.Boom.preconditionFailed();
Generates the following response payload:
{
"statusCode": 412,
"error": "Precondition Failed"
}
Boom.entityTooLarge([message], [data])Returns a 413 Request Entity Too Large error where:
message - optional message.data - optional additional error data.Boom.entityTooLarge('too big');
Generates the following response payload:
{
"statusCode": 413,
"error": "Request Entity Too Large",
"message": "too big"
}
Boom.uriTooLong([message], [data])Returns a 414 Request-URI Too Large error where:
message - optional message.data - optional additional error data.Boom.uriTooLong('uri is too long');
Generates the following response payload:
{
"statusCode": 414,
"error": "Request-URI Too Large",
"message": "uri is too long"
}
Boom.unsupportedMediaType([message], [data])Returns a 415 Unsupported Media Type error where:
message - optional message.data - optional additional error data.Boom.unsupportedMediaType('that media is not supported');
Generates the following response payload:
{
"statusCode": 415,
"error": "Unsupported Media Type",
"message": "that media is not supported"
}
Boom.rangeNotSatisfiable([message], [data])Returns a 416 Requested Range Not Satisfiable error where:
message - optional message.data - optional additional error data.Boom.rangeNotSatisfiable();
Generates the following response payload:
{
"statusCode": 416,
"error": "Requested Range Not Satisfiable"
}
Boom.expectationFailed([message], [data])Returns a 417 Expectation Failed error where:
message - optional message.data - optional additional error data.Boom.expectationFailed('expected this to work');
Generates the following response payload:
{
"statusCode": 417,
"error": "Expectation Failed",
"message": "expected this to work"
}
Boom.teapot([message], [data])Returns a 418 I'm a Teapot error where:
message - optional message.data - optional additional error data.Boom.teapot('sorry, no coffee...');
Generates the following response payload:
{
"statusCode": 418,
"error": "I'm a Teapot",
"message": "Sorry, no coffee..."
}
Boom.badData([message], [data])Returns a 422 Unprocessable Entity error where:
message - optional message.data - optional additional error data.Boom.badData('your data is bad and you should feel bad');
Generates the following response payload:
{
"statusCode": 422,
"error": "Unprocessable Entity",
"message": "your data is bad and you should feel bad"
}
Boom.locked([message], [data])Returns a 423 Locked error where:
message - optional message.data - optional additional error data.Boom.locked('this resource has been locked');
Generates the following response payload:
{
"statusCode": 423,
"error": "Locked",
"message": "this resource has been locked"
}
Boom.failedDependency([message], [data])Returns a 424 Failed Dependency error where:
message - optional message.data - optional additional error data.Boom.failedDependency('an external resource failed');
Generates the following response payload:
{
"statusCode": 424,
"error": "Failed Dependency",
"message": "an external resource failed"
}
Boom.preconditionRequired([message], [data])Returns a 428 Precondition Required error where:
message - optional message.data - optional additional error data.Boom.preconditionRequired('you must supply an If-Match header');
Generates the following response payload:
{
"statusCode": 428,
"error": "Precondition Required",
"message": "you must supply an If-Match header"
}
Boom.tooManyRequests([message], [data])Returns a 429 Too Many Requests error where:
message - optional message.data - optional additional error data.Boom.tooManyRequests('you have exceeded your request limit');
Generates the following response payload:
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "you have exceeded your request limit"
}
Boom.illegal([message], [data])Returns a 451 Unavailable For Legal Reasons error where:
message - optional message.data - optional additional error data.Boom.illegal('you are not permitted to view this resource for legal reasons');
Generates the following response payload:
{
"statusCode": 451,
"error": "Unavailable For Legal Reasons",
"message": "you are not permitted to view this resource for legal reasons"
}
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.badImplementation('terrible implementation');
Generates the following response payload:
{
"statusCode": 500,
"error": "Internal Server Error",
"message": "An internal server error occurred"
}
Boom.notImplemented([message], [data])Returns a 501 Not Implemented error where:
message - optional message.data - optional additional error data.Boom.notImplemented('method not implemented');
Generates the following response payload:
{
"statusCode": 501,
"error": "Not Implemented",
"message": "method not implemented"
}
Boom.badGateway([message], [data])Returns a 502 Bad Gateway error where:
message - optional message.data - optional additional error data.Boom.badGateway('that is a bad gateway');
Generates the following response payload:
{
"statusCode": 502,
"error": "Bad Gateway",
"message": "that is a bad gateway"
}
Boom.serverUnavailable([message], [data])Returns a 503 Service Unavailable error where:
message - optional message.data - optional additional error data.Boom.serverUnavailable('unavailable');
Generates the following response payload:
{
"statusCode": 503,
"error": "Service Unavailable",
"message": "unavailable"
}
Boom.gatewayTimeout([message], [data])Returns a 504 Gateway Time-out error where:
message - optional message.data - optional additional error data.Boom.gatewayTimeout();
Generates the following response payload:
{
"statusCode": 504,
"error": "Gateway Time-out"
}
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.