diff --git a/docs/subsystems/logging.md b/docs/subsystems/logging.md
index 1ab45e9f67..0b20416e32 100644
--- a/docs/subsystems/logging.md
+++ b/docs/subsystems/logging.md
@@ -32,9 +32,8 @@ infrastructure needed by our error reporting system:
 * A nice framework for filtering passwords and other important user
   data from the exception details, which we use in
   `zerver/filters.py`.
-* Middleware for handling `JsonableError`, our system for allowing
-  code anywhere in Django to report an API-facing `json_error` from
-  anywhere in a view code path.
+* Middleware for handling `JsonableError`, which is our standard
+  system for API code to return a JSON-format HTTP error response.
 
 Since 500 errors in any Zulip server are usually a problem the server
 administrator should investigate and/or report upstream, we have this
diff --git a/docs/tutorials/life-of-a-request.md b/docs/tutorials/life-of-a-request.md
index f09c88d7ca..96a56c3501 100644
--- a/docs/tutorials/life-of-a-request.md
+++ b/docs/tutorials/life-of-a-request.md
@@ -193,9 +193,9 @@ This is covered in good detail in the [writing views doc](writing-views.md).
 ## Results are given as JSON
 
 Our API works on JSON requests and responses. Every API endpoint should
-return `json_error` in the case of an error, which gives a JSON string:
+`raise JsonableError` in the case of an error, which gives a JSON string:
 
-`{'result': 'error', 'msg': <some error message>}`
+`{'result': 'error', 'msg': <some error message>, 'code': 'BAD_REQUEST'}`
 
 in a
 [HTTP response](https://docs.djangoproject.com/en/1.8/ref/request-response/)
diff --git a/docs/tutorials/new-feature-tutorial.md b/docs/tutorials/new-feature-tutorial.md
index 07f234d864..8bbfaa95de 100644
--- a/docs/tutorials/new-feature-tutorial.md
+++ b/docs/tutorials/new-feature-tutorial.md
@@ -437,7 +437,7 @@ can be handled at the beginning of `update_realm`.
     if default_language is not None and default_language not in get_available_language_codes():
         raise JsonableError(_("Invalid language '%s'" % (default_language,)))
     if description is not None and len(description) > 100:
-        return json_error(_("Realm description cannot exceed 100 characters."))
+        raise JsonableError(_("Realm description cannot exceed 100 characters."))
     # ...
 
 The code in `update_realm` loops through the `property_types` dictionary