diff --git a/docs/api/context.md b/docs/api/context.md
index 56d2f32..d05e8e1 100644
--- a/docs/api/context.md
+++ b/docs/api/context.md
@@ -118,7 +118,7 @@ throw err;
 ctx.throw(401, 'access_denied', { user: user });
 ```
 
-Koa uses [http-errors](https://github.com/jshttp/http-errors) to create errors.
+Koa uses [http-errors](https://github.com/jshttp/http-errors) to create errors. `status` should only be passed as the first parameter.
 
 ### ctx.assert(value, [status], [msg], [properties])
 
diff --git a/lib/context.js b/lib/context.js
index 1b92f01..7d80df2 100644
--- a/lib/context.js
+++ b/lib/context.js
@@ -73,19 +73,20 @@ const proto = module.exports = {
   assert: httpAssert,
 
   /**
-   * Throw an error with `msg` and optional `status`
-   * defaulting to 500. Note that these are user-level
+   * Throw an error with `status` (default 500) and
+   * `msg`. Note that these are user-level
    * errors, and the message may be exposed to the client.
    *
    *    this.throw(403)
-   *    this.throw('name required', 400)
    *    this.throw(400, 'name required')
    *    this.throw('something exploded')
-   *    this.throw(new Error('invalid'), 400);
-   *    this.throw(400, new Error('invalid'));
+   *    this.throw(new Error('invalid'))
+   *    this.throw(400, new Error('invalid'))
    *
    * See: https://github.com/jshttp/http-errors
    *
+   * Note: `stats` should only be passed as the first parameter.
+   *
    * @param {String|Number|Error} err, msg or status
    * @param {String|Number|Error} [err, msg or status]
    * @param {Object} [props]