Merge pull request #1092 from rouge8/custom-exception-handler-setting

Support customizable view EXCEPTION_HANDLER (#907)

2 files changed, 34 insertions, 2 deletions

diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md
index 8b3e50f1..fa5053df 100644
--- a/docs/api-guide/exceptions.md
+++ b/docs/api-guide/exceptions.md
@@ -30,9 +30,27 @@ Might receive an error response indicating that the `DELETE` method is not allow
     HTTP/1.1 405 Method Not Allowed
     Content-Type: application/json; charset=utf-8
     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:
+
+    exception_handler(exc)
+
+* `exc`: The exception.
+
+If the function returns `None`, a 500 error will be raised.
+
+The exception handler is set globally, using the `EXCEPTION_HANDLER` setting. For example:
+
+    'EXCEPTION_HANDLER': 'project.app.module.function'
+
+If not specified, this setting defaults to the exception handler described above:
+
+    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
+
 ---
 
 # API Reference
diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md
index 542e8c5f..13f96f9a 100644
--- a/docs/api-guide/settings.md
+++ b/docs/api-guide/settings.md
@@ -25,7 +25,7 @@ If you need to access the values of REST framework's API settings in your projec
 you should use the `api_settings` object.  For example.
 
     from rest_framework.settings import api_settings
-    
+
     print api_settings.DEFAULT_AUTHENTICATION_CLASSES
 
 The `api_settings` object will check for any user-defined settings, and otherwise fall back to the default values.  Any setting that uses string import paths to refer to a class will automatically import and return the referenced class, instead of the string literal.
@@ -339,6 +339,20 @@ Default: `'rest_framework.views.get_view_description'`
 
 ## Miscellaneous settings
 
+#### EXCEPTION_HANDLER
+
+A string representing the function that should be used when returning a response for any given exception.  If the function returns `None`, a 500 error will be raised.
+
+This setting can be changed to support error responses other than the default `{"detail": "Failure..."}` responses.  For example, you can use it to provide API responses like `{"errors": [{"message": "Failure...", "code": ""} ...]}`.
+
+This should be a function with the following signature:
+
+    exception_handler(exc)
+
+* `exc`: The exception.
+
+Default: `'rest_framework.views.exception_handler'`
+
 #### FORMAT_SUFFIX_KWARG
 
 The name of a parameter in the URL conf that may be used to provide a format suffix.