1  # http-errors
  2  
  3  [![NPM Version][npm-version-image]][npm-url]
  4  [![NPM Downloads][npm-downloads-image]][node-url]
  5  [![Node.js Version][node-image]][node-url]
  6  [![Build Status][travis-image]][travis-url]
  7  [![Test Coverage][coveralls-image]][coveralls-url]
  8  
  9  Create HTTP errors for Express, Koa, Connect, etc. with ease.
 10  
 11  ## Install
 12  
 13  This is a [Node.js](https://nodejs.org/en/) module available through the
 14  [npm registry](https://www.npmjs.com/). Installation is done using the
 15  [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
 16  
 17  ```bash
 18  $ npm install http-errors
 19  ```
 20  
 21  ## Example
 22  
 23  ```js
 24  var createError = require('http-errors')
 25  var express = require('express')
 26  var app = express()
 27  
 28  app.use(function (req, res, next) {
 29    if (!req.user) return next(createError(401, 'Please login to view this page.'))
 30    next()
 31  })
 32  ```
 33  
 34  ## API
 35  
 36  This is the current API, currently extracted from Koa and subject to change.
 37  
 38  ### Error Properties
 39  
 40  - `expose` - can be used to signal if `message` should be sent to the client,
 41    defaulting to `false` when `status` >= 500
 42  - `headers` - can be an object of header names to values to be sent to the
 43    client, defaulting to `undefined`. When defined, the key names should all
 44    be lower-cased
 45  - `message` - the traditional error message, which should be kept short and all
 46    single line
 47  - `status` - the status code of the error, mirroring `statusCode` for general
 48    compatibility
 49  - `statusCode` - the status code of the error, defaulting to `500`
 50  
 51  ### createError([status], [message], [properties])
 52  
 53  Create a new error object with the given message `msg`.
 54  The error object inherits from `createError.HttpError`.
 55  
 56  <!-- eslint-disable no-undef, no-unused-vars -->
 57  
 58  ```js
 59  var err = createError(404, 'This video does not exist!')
 60  ```
 61  
 62  - `status: 500` - the status code as a number
 63  - `message` - the message of the error, defaulting to node's text for that status code.
 64  - `properties` - custom properties to attach to the object
 65  
 66  ### createError([status], [error], [properties])
 67  
 68  Extend the given `error` object with `createError.HttpError`
 69  properties. This will not alter the inheritance of the given
 70  `error` object, and the modified `error` object is the
 71  return value.
 72  
 73  <!-- eslint-disable no-redeclare, no-undef, no-unused-vars -->
 74  
 75  ```js
 76  fs.readFile('foo.txt', function (err, buf) {
 77    if (err) {
 78      if (err.code === 'ENOENT') {
 79        var httpError = createError(404, err, { expose: false })
 80      } else {
 81        var httpError = createError(500, err)
 82      }
 83    }
 84  })
 85  ```
 86  
 87  - `status` - the status code as a number
 88  - `error` - the error object to extend
 89  - `properties` - custom properties to attach to the object
 90  
 91  ### new createError\[code || name\](\[msg]\))
 92  
 93  Create a new error object with the given message `msg`.
 94  The error object inherits from `createError.HttpError`.
 95  
 96  <!-- eslint-disable no-undef, no-unused-vars -->
 97  
 98  ```js
 99  var err = new createError.NotFound()
100  ```
101  
102  - `code` - the status code as a number
103  - `name` - the name of the error as a "bumpy case", i.e. `NotFound` or `InternalServerError`.
104  
105  #### List of all constructors
106  
107  |Status Code|Constructor Name             |
108  |-----------|-----------------------------|
109  |400        |BadRequest                   |
110  |401        |Unauthorized                 |
111  |402        |PaymentRequired              |
112  |403        |Forbidden                    |
113  |404        |NotFound                     |
114  |405        |MethodNotAllowed             |
115  |406        |NotAcceptable                |
116  |407        |ProxyAuthenticationRequired  |
117  |408        |RequestTimeout               |
118  |409        |Conflict                     |
119  |410        |Gone                         |
120  |411        |LengthRequired               |
121  |412        |PreconditionFailed           |
122  |413        |PayloadTooLarge              |
123  |414        |URITooLong                   |
124  |415        |UnsupportedMediaType         |
125  |416        |RangeNotSatisfiable          |
126  |417        |ExpectationFailed            |
127  |418        |ImATeapot                    |
128  |421        |MisdirectedRequest           |
129  |422        |UnprocessableEntity          |
130  |423        |Locked                       |
131  |424        |FailedDependency             |
132  |425        |UnorderedCollection          |
133  |426        |UpgradeRequired              |
134  |428        |PreconditionRequired         |
135  |429        |TooManyRequests              |
136  |431        |RequestHeaderFieldsTooLarge  |
137  |451        |UnavailableForLegalReasons   |
138  |500        |InternalServerError          |
139  |501        |NotImplemented               |
140  |502        |BadGateway                   |
141  |503        |ServiceUnavailable           |
142  |504        |GatewayTimeout               |
143  |505        |HTTPVersionNotSupported      |
144  |506        |VariantAlsoNegotiates        |
145  |507        |InsufficientStorage          |
146  |508        |LoopDetected                 |
147  |509        |BandwidthLimitExceeded       |
148  |510        |NotExtended                  |
149  |511        |NetworkAuthenticationRequired|
150  
151  ## License
152  
153  [MIT](LICENSE)
154  
155  [coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/http-errors/master
156  [coveralls-url]: https://coveralls.io/r/jshttp/http-errors?branch=master
157  [node-image]: https://badgen.net/npm/node/http-errors
158  [node-url]: https://nodejs.org/en/download
159  [npm-downloads-image]: https://badgen.net/npm/dm/http-errors
160  [npm-url]: https://npmjs.org/package/http-errors
161  [npm-version-image]: https://badgen.net/npm/v/http-errors
162  [travis-image]: https://badgen.net/travis/jshttp/http-errors/master
163  [travis-url]: https://travis-ci.org/jshttp/http-errors