From b0a289fba4da23630d5818be3cd1efb1cc3a359d Mon Sep 17 00:00:00 2001
From: Douglas Christopher Wilson <doug@somethingdoug.com>
Date: Wed, 15 Apr 2015 23:51:03 -0400
Subject: [PATCH] docs: add error documentation

closes #91
---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/README.md b/README.md
index 8a7d6a8b..b8c12476 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,11 @@ $ npm install body-parser
 var bodyParser = require('body-parser')
 ```
 
+The `bodyParser` object exposes various factories to create middlewares. All
+middlewares will populate the `req.body` property with the parsed body or
+provide an error to the callback. The various errors are described in the
+[errors section](#errors).
+
 ### bodyParser.json(options)
 
 Returns middleware that only parses `json`. This parser accepts any Unicode
@@ -250,6 +255,62 @@ The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`
 where `buf` is a `Buffer` of the raw request body and `encoding` is the
 encoding of the request. The parsing can be aborted by throwing an error.
 
+## Errors
+
+The middlewares provided by this module create errors depending on the error
+condition during parsing. The errors will typically have a `status` property
+that contains the suggested HTTP response code.
+
+The following are the common errors emitted, though any error can come through
+for various reasons.
+
+### content encoding unsupported
+
+This error will occur when the request had a `Content-Encoding` header that
+contained an encoding but the "inflation" option was set to `false`. The
+`status` property is set to `415`.
+
+### request aborted
+
+This error will occur when the request is aborted by the client before reading
+the body has finished. The `received` property will be set to the number of
+bytes received before the request was aborted and the `expected` property is
+set to the number of expected bytes. The `status` property is set to `400`.
+
+### request entity too large
+
+This error will occur when the request body's size is larger than the "limit"
+option. The `limit` property will be set to the byte limit and the `length`
+property will be set to the request body's length. The `status` property is
+set to `413`.
+
+### request size did not match content length
+
+This error will occur when the request's length did not match the length from
+the `Content-Lentgh` header. This typically occurs when the requst is malformed,
+typically when the `Content-Length` header was calculated based on characters
+instead of bytes. The `status` property is set to `400`.
+
+### stream encoding should not be set
+
+This error will occur when something called the `req.setEncoding` method prior
+to this middleware. This module operates directly on bytes only and you cannot
+call `req.setEncoding` when using this module. The `status` property is set to
+`500`.
+
+### unsupported charset "BOGUS"
+
+This error will occur when the request had a charset parameter in the
+`Content-Type` header, but the `iconv-lite` module does not support it OR the
+parser does not support it. The charset is contained in the message as well
+as in the `charset` property. The `status` property is set to `415`.
+
+### unsupported content encoding "bogus"
+
+This error will occur when the request had a `Content-Encoding` header that
+contained an unsupported encoding. The encoding is contained in the message
+as well as in the `encoding` property. The `status` property is set to `415`.
+
 ## Examples
 
 ### express/connect top-level generic