Fix #1908, document fields. [skip ci] (#2314)

docs/change-log.md

@@ -25,6 +25,7 @@
 - API: Assigning to `vnode.state` (as in `vnode.state = ...`) is no longer supported. Instead, an error is thrown if `vnode.state` changes upon the invocation of a lifecycle hook.
 - API: `m.request` will no longer reject the Promise on server errors (eg. status >= 400) if the caller supplies an `extract` callback. This gives applications more control over handling server responses.
 - hyperscript: when attributes have a `null` or `undefined` value, they are treated as if they were absent. [#1773](https://github.com/MithrilJS/mithril.js/issues/1773) ([#2174](https://github.com/MithrilJS/mithril.js/pull/2174))
+- API: `m.request` errors no longer copy response fields to the error, but instead assign the parsed JSON response to `error.response` and the HTTP status code `error.code`.
 - hyperscript: when an attribute is defined on both the first and second argument (as a CSS selector and an `attrs` field, respectively), the latter takes precedence, except for `class` attributes that are still added together. [#2172](https://github.com/MithrilJS/mithril.js/issues/2172) ([#2174](https://github.com/MithrilJS/mithril.js/pull/2174))
 - stream: when a stream conditionally returns HALT, dependant stream will also end ([#2200](https://github.com/MithrilJS/mithril.js/pull/2200))
 - render: remove some redundancy within the component initialization code ([#2213](https://github.com/MithrilJS/mithril.js/pull/2213))

docs/request.md

@@ -4,6 +4,7 @@
 - [Signature](#signature)
 - [How it works](#how-it-works)
 - [Typical usage](#typical-usage)
+- [Error handling](#error-handling)
 - [Loading icons and error messages](#loading-icons-and-error-messages)
 - [Dynamic URLs](#dynamic-urls)
 - [Aborting requests](#aborting-requests)
@@ -127,6 +128,18 @@ When `m.route` is called at the bottom, the `Todos` component is initialized. `o
 
 ---
 
+### Error handling
+
+When a non-`file:` request returns with any status other than 2xx or 304, it rejects with an error. This error is a normal [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) instance, but with a few special properties.
+
+- `error.message` is set to the raw response text.
+- `error.code` is set to the status code itself.
+- `error.response` is set to the parsed response, using `options.extract` and `options.deserialize` as is done with normal responses.
+
+This is useful in many cases where errors are themselves things you can account for. If you want to detect if a session expired - you can do `if (error.code === 401) return promptForAuth().then(retry)`. If you hit an API's throttling mechanism and it returned an error with a `"timeout": 1000`, you could do a `setTimeout(retry, error.response.timeout)`.
+
+---
+
 ### Loading icons and error messages
 
 Here's an expanded version of the example above that implements a loading indicator and an error message: