Extra docs on custom exception handling.

tomchristie · tomchristie · commit b6c0c815aa75 · 2013-09-07T20:45:43.000+01:00
diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md
@@ -28,28 +28,53 @@ For example, the following request:
 Might receive an error response indicating that the `DELETE` method is not allowed on that resource:
 
     HTTP/1.1 405 Method Not Allowed
-    Content-Type: application/json; charset=utf-8
+    Content-Type: application/json
     Content-Length: 42
 
     {"detail": "Method 'DELETE' not allowed."}
 
 ## Custom exception handling
 
-To implement custom exception handling (e.g. to handle additional exception classes or to override the error response format), create an exception handler function with the following signature:
+You can implement custom exception handling by creating a handler function that converts exceptions raised in your API views into response objects.  This allows you to control the style of error responses used by your API.
 
-    exception_handler(exc)
+The function must take a single argument, which is the exception to be handled, and should either return a `Response` object, or return `None` if the exception cannot be handled.  If the handler returns `None` then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.
 
-* `exc`: The exception.
+For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:
 
-If the function returns `None`, a 500 error will be raised.
+    HTTP/1.1 405 Method Not Allowed
+    Content-Type: application/json
+    Content-Length: 62
+
+    {"status_code": 405, "detail": "Method 'DELETE' not allowed."}
+
+In order to alter the style of the response, you could write the following custom exception handler:
+
+    from rest_framework.views import exception_handler
+
+    def custom_exception_handler(exc):
+        # Call REST framework's default exception handler first,
+        # to get the standard error response.
+        response = exception_handler(exc)
+
+        # Now add the HTTP status code to the response.
+        if response is not None:
+            response.data['status_code'] = response.status_code
+
+        return response
+
+The exception handler must also be configured in your settings, using the `EXCEPTION_HANDLER` setting key. For example:
 
-The exception handler is set globally, using the `EXCEPTION_HANDLER` setting. For example:
+    REST_FRAMEWORK = {
+        'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
+    }
 
-    'EXCEPTION_HANDLER': 'project.app.module.function'
+If not specified, the `'EXCEPTION_HANDLER'` setting defaults to the standard exception handler provided by REST framework:
 
-If not specified, this setting defaults to the exception handler described above:
+    REST_FRAMEWORK = {
+        'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
+    }
 
-    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
+Note that the exception handler will only be called for responses generated by raised exceptions.  It will not be used for any responses returned directly by the view, such as the `HTTP_400_BAD_REQUEST` responses that are returned by the generic views when serializer validation fails.
 
 ---
 
