diff --git a/docs/api/context.md b/docs/api/context.md
index 0ad938c..bece061 100644
--- a/docs/api/context.md
+++ b/docs/api/context.md
@@ -75,17 +75,17 @@ Note: koa uses the [cookies](https://github.com/jed/cookies) module where option
 
 Note: koa uses the [cookies](https://github.com/jed/cookies) module where options are simply passed.
 
-### ctx.throw(msg, [status])
+### ctx.throw(msg, [status], [properties])
 
   Helper method to throw an error with a `.status` property
   defaulting to `500` that will allow Koa to respond appropriately.
   The following combinations are allowed:
 
 ```js
-this.throw(403)
-this.throw('name required', 400)
-this.throw(400, 'name required')
-this.throw('something exploded')
+this.throw(403);
+this.throw('name required', 400);
+this.throw(400, 'name required');
+this.throw('something exploded');
 ```
 
   For example `this.throw('name required', 400)` is equivalent to:
@@ -102,6 +102,12 @@ throw err;
   error messages since you do not want to leak failure
   details.
 
+  You may optionall pass a `properties` object which is merged into the error as-is, useful for decorating machine-friendly errors which are reported to the requester upstream.
+
+```js
+this.throw(401, 'access_denied', { user: user });
+```
+
 ### ctx.respond
 
   To bypass Koa's built-in response handling, you may explicitly set `this.respond = false;`. Use this if you want to write to the raw `res` object instead of letting Koa handle the response for you.