http-json-errors

A Node package that exposes standardized error creation functions and a class. This package was written for Express but doesn't have any dependencies on Express or any other package, except for development.

Example

import { BadRequest } from 'http-json-errors'

throw new BadRequest('You done messed up, son!')

{
  isHttpError: true,
  statusCode: 400,
  title: 'Bad Request',
  message: 'You done messed up, son!',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400',
  body: {
    error_text: 'You done messed up, son!'
  }
}

Generate Standard Errors by Http Status Code

If you don't know the error type up front, but do know the code, use the createError function to get a custom class, or a generic one, if the status code can't be matched:

import { createError } from 'http-json-errors'

throw createError(401, 'OMG!')

{
  isHttpError: true,
  statusCode: 401,
  title: 'Unauthorized',
  message: 'OMG!',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401',
  body: {
    error_text: 'OMG!'
  }
}

Roll your own

Create your own custom Error message using the HttpError class:

import { HttpError } from 'http-json-errors'

throw new HttpError(401, {message: 'OMG!', body: { error_code: 'OMG!', error_text: 'I wish you wouldn\'t have done that.' } });

{
  isHttpError: true,
  statusCode: 401,
  title: 'Internal Server Error',
  message: 'OMG!',
  body: {
    error_code: 'OMG!',
    error_text: "I wish you wouldn't have done that."
  }
}

TypeScript + ES6

This project was built in TypeScript and contains exported interfaces and type definitions for your convenience. The module is designed to use ES6 imports.

// Check out the Custom HTTP Error Classes section for a full list of custom classes!
import { BadRequest, HttpErrorOptions } from 'http-json-errors'

function totallyThrowsABadRequestError(options: HttpErrorOptions) {
  throw new BadRequest(options)
}
totallyThrowsABadRequestError('The user did something completely new that NOONE foresaw')

{
  isHttpError: true,
  statusCode: 400,
  title: 'Bad Request',
  message: 'The user did something completely new that NOONE foresaw',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400',
  body: {
    error_text: 'The user did something completely new that NOONE foresaw'
  }
}

Control over responses

Note that in the examples above the returned object contains both Error detail and a response body that can be returned to the user. The body defaults to an object with the format below. Any stand-alone strings will be assigned to the message property, and if the status is < 500, this will be copied to the body.

import { HttpError } from 'http-json-errors'

throw new HttpError(400, 'Bad stuff happened')

{
  isHttpError: true,
  statusCode: 400,
  title: 'Internal Server Error',
  message: 'Bad stuff happened',
  body: { error_text: 'Bad stuff happened' }
}

If the error code is >= 500, you should provide a body by passing an HttpErrorOptions object (one of the exported TypeScript interfaces). Note that any options provided in this way overwrite the default options.

import { HttpError } from 'http-json-errors'

throw new HttpError(500, 'Bad stuff happened', {body: {error_code: 'Why', error_description: 'You did the thing you should not have done' }})

{
  isHttpError: true,
  statusCode: 500,
  title: 'Internal Server Error',
  message: 'Bad stuff happened',
  body: {
    error_code: 'Why',
    error_description: 'You did the thing you should not have done'
  }
}

new BadRequest('Bad stuff happened', {body: 'That was not good'})

  isHttpError: true,
  statusCode: 400,
  title: 'Bad Request',
  message: 'Bad stuff happened',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400',
  body: 'That was not good'
}

import { NotImplemented } from 'http-json-errors'

throw new NotImplemented({body: {excuse: 'I just write the code. THEY designed the damn thing'}})

{
  isHttpError: true,
  statusCode: 501,
  title: 'Not Implemented',
  message: 'The request method is not supported by the server and cannot be handled.',
  type: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501',
  body: { excuse: 'I just write the code. THEY designed the damn thing' }
}

Custom HTTP Error Classes

The following custom classes are available:

HTTP Status Code | Exported Class Name --- | ---------------------------- 400 | BadRequest 401 | Unauthorized 403 | Forbidden 404 | NotFound 405 | MethodNotAllowed 406 | NotAcceptable 407 | ProxyAuthenticationRequired 408 | RequestTimeout 409 | Conflict 410 | Gone 411 | LengthRequired 412 | PreconditionFailed 413 | PayloadTooLarge 414 | URITooLong 415 | UnsupportedMediaType 416 | RangeNotSatisfiable 417 | ExpectationFailed 418 | ImATeapot 421 | MisdirectedRequest 422 | UnprocessableEntity 423 | Locked 424 | FailedDependency 425 | TooEarly 426 | UpgradeRequired 428 | PreconditionRequired 429 | TooManyRequests 431 | RequestHeaderFieldsTooLarge 451 | UnavailableForLegalReasons 500 | InternalServerError 501 | NotImplemented 502 | BadGateway 503 | ServiceUnavailable 504 | GatewayTimeout 505 | HTTPVersionNotSupported 506 | VariantAlsoNegotiates 507 | InsufficientStorage 511 | NetworkAuthenticationRequired

Changelog

Version | Notes --- | --- 1.2.0 | Initial release: Why start at 1? 1.2.1 | Updates to Readme; Added type file headers; Added .editorconfig; 1.2.2 | Fixed name in readme 1.2.3 | Added body and isHttpError properties to HttpError class; Security update for mocha; Updated Readme with new content and more examples 1.2.4 | Changed statusCode to primary status property to be in line with NodeJS; status is now just a read-only property; Updated tests to reflect change 1.2.5 | A string passed to a custom class will be set as the body error_text value. Updated examples to reflect the change. Updated dev dependency versions. 1.2.6 | Developer environment updates: updated to [email protected]; Removed all implicit any values; replaced object with Record<string, any>; migrated from tslint to eslint; added VSCode settings. 1.2.7-1.2.8 | Updates to NPM package 1.2.9 | Updated mocha to address security advisory: https://github.com/advisories/GHSA-p9pc-299p-vxgp; 1.2.10 | Updated typo for status 425 1.2.11 | Fixed a bug where a value starting with 3 numbers would be mis-construed as a status code. 1.2.12 | Updated mocha and chai to address vulnerabilities.