diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst
index f8b78801..49bf67ba 100644
--- a/docs/user/quickstart.rst
+++ b/docs/user/quickstart.rst
@@ -145,8 +145,14 @@ There's also a builtin JSON decoder, in case you're dealing with JSON data::
     [{u'repository': {u'open_issues': 0, u'url': 'https://github.com/...
 
 In case the JSON decoding fails, ``r.json`` raises an exception. For example, if
-the response gets a 401 (Unauthorized), attempting ``r.json`` raises ``ValueError:
-No JSON object could be decoded``
+the response gets a 204 (No Content), or if the response contains invalid JSON,
+attempting ``r.json`` raises ``ValueError: No JSON object could be decoded``.
+
+It should be noted that the success of the call to ``r.json`` does **not**
+indicate the success of the response. Some servers may return a JSON object in a
+failed response (e.g. error details with HTTP 500). Such JSON will be decoded
+and returned. To check that a request is successful, use ``r.ok == True`` or
+``r.raise_for_status()``.
 
 
 Raw Response Content