Exceptions… allow error handling to be organized cleanly in a central or high-level place within the program structure.
— Doug Hellmann,Python Exception Handling Techniques
REST framework's views handle various exceptions, and deal with returning appropriate error responses.
The handled exceptions are:
APIException raised inside REST framework.Http404 exception.PermissionDenied exception.In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.
Most error responses will include a keydetail in the body of the response.
For example, the following request:
DELETE http://api.example.com/foo/bar HTTP/1.1Accept: application/jsonMight receive an error response indicating that theDELETE method is not allowed on that resource:
HTTP/1.1 405 Method Not AllowedContent-Type: application/jsonContent-Length: 42{"detail": "Method 'DELETE' not allowed."}Validation errors are handled slightly differently, and will include the field names as the keys in the response. If the validation error was not specific to a particular field then it will use the "non_field_errors" key, or whatever string value has been set for theNON_FIELD_ERRORS_KEY setting.
An example validation error might look like this:
HTTP/1.1 400 Bad RequestContent-Type: application/jsonContent-Length: 94{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}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.
The function must take a pair of arguments, the first is the exception to be handled, and the second is a dictionary containing any extra context such as the view currently being handled. The exception handler function should either return aResponse object, or returnNone if the exception cannot be handled. If the handler returnsNone then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.
For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:
HTTP/1.1 405 Method Not AllowedContent-Type: application/jsonContent-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_handlerdef custom_exception_handler(exc, context): # Call REST framework's default exception handler first, # to get the standard error response. response = exception_handler(exc, context) # Now add the HTTP status code to the response. if response is not None: response.data['status_code'] = response.status_code return responseThe context argument is not used by the default handler, but can be useful if the exception handler needs further information such as the view currently being handled, which can be accessed ascontext['view'].
The exception handler must also be configured in your settings, using theEXCEPTION_HANDLER setting key. For example:
REST_FRAMEWORK = { 'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'}If not specified, the'EXCEPTION_HANDLER' setting defaults to the standard exception handler provided by REST framework:
REST_FRAMEWORK = { '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 theHTTP_400_BAD_REQUEST responses that are returned by the generic views when serializer validation fails.
Signature:APIException()
Thebase class for all exceptions raised inside anAPIView class or@api_view.
To provide a custom exception, subclassAPIException and set the.status_code,.default_detail, and.default_code attributes on the class.
For example, if your API relies on a third party service that may sometimes be unreachable, you might want to implement an exception for the "503 Service Unavailable" HTTP response code. You could do this like so:
from rest_framework.exceptions import APIExceptionclass ServiceUnavailable(APIException): status_code = 503 default_detail = 'Service temporarily unavailable, try again later.' default_code = 'service_unavailable'There are a number of different properties available for inspecting the statusof an API exception. You can use these to build custom exception handlingfor your project.
The available attributes and methods are:
.detail - Return the textual description of the error..get_codes() - Return the code identifier of the error..get_full_details() - Return both the textual description and the code identifier.In most cases the error detail will be a simple item:
>>> print(exc.detail)You do not have permission to perform this action.>>> print(exc.get_codes())permission_denied>>> print(exc.get_full_details()){'message':'You do not have permission to perform this action.','code':'permission_denied'}In the case of validation errors the error detail will be either a list ordictionary of items:
>>> print(exc.detail){"name":"This field is required.","age":"A valid integer is required."}>>> print(exc.get_codes()){"name":"required","age":"invalid"}>>> print(exc.get_full_details()){"name":{"message":"This field is required.","code":"required"},"age":{"message":"A valid integer is required.","code":"invalid"}}Signature:ParseError(detail=None, code=None)
Raised if the request contains malformed data when accessingrequest.data.
By default this exception results in a response with the HTTP status code "400 Bad Request".
Signature:AuthenticationFailed(detail=None, code=None)
Raised when an incoming request includes incorrect authentication.
By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See theauthentication documentation for more details.
Signature:NotAuthenticated(detail=None, code=None)
Raised when an unauthenticated request fails the permission checks.
By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See theauthentication documentation for more details.
Signature:PermissionDenied(detail=None, code=None)
Raised when an authenticated request fails the permission checks.
By default this exception results in a response with the HTTP status code "403 Forbidden".
Signature:NotFound(detail=None, code=None)
Raised when a resource does not exist at the given URL. This exception is equivalent to the standardHttp404 Django exception.
By default this exception results in a response with the HTTP status code "404 Not Found".
Signature:MethodNotAllowed(method, detail=None, code=None)
Raised when an incoming request occurs that does not map to a handler method on the view.
By default this exception results in a response with the HTTP status code "405 Method Not Allowed".
Signature:NotAcceptable(detail=None, code=None)
Raised when an incoming request occurs with anAccept header that cannot be satisfied by any of the available renderers.
By default this exception results in a response with the HTTP status code "406 Not Acceptable".
Signature:UnsupportedMediaType(media_type, detail=None, code=None)
Raised if there are no parsers that can handle the content type of the request data when accessingrequest.data.
By default this exception results in a response with the HTTP status code "415 Unsupported Media Type".
Signature:Throttled(wait=None, detail=None, code=None)
Raised when an incoming request fails the throttling checks.
By default this exception results in a response with the HTTP status code "429 Too Many Requests".
Signature:ValidationError(detail=None, code=None)
TheValidationError exception is slightly different from the otherAPIException classes:
detail argument may be a list or dictionary of error details, and may also be a nested data structure. By using a dictionary, you can specify field-level errors while performing object-level validation in thevalidate() method of a serializer. For example.raise serializers.ValidationError({'name': 'Please enter a valid name.'})ValidationError style, in order to differentiate it from Django's built-in validation error. For example.raise serializers.ValidationError('This field must be an integer value.')TheValidationError class should be used for serializer and field validation, and by validator classes. It is also raised when callingserializer.is_valid with theraise_exception keyword argument:
serializer.is_valid(raise_exception=True)The generic views use theraise_exception=True flag, which means that you can override the style of validation error responses globally in your API. To do so, use a custom exception handler, as described above.
By default this exception results in a response with the HTTP status code "400 Bad Request".
Django REST Framework provides two error views suitable for providing generic JSON500 Server Error and400 Bad Request responses. (Django's default error views provide HTML responses, which may not be appropriate for anAPI-only application.)
Use these as perDjango's Customizing error views documentation.
rest_framework.exceptions.server_errorReturns a response with status code500 andapplication/json content type.
Set ashandler500:
handler500 = 'rest_framework.exceptions.server_error'rest_framework.exceptions.bad_requestReturns a response with status code400 andapplication/json content type.
Set ashandler400:
handler400 = 'rest_framework.exceptions.bad_request'The following third-party packages are also available.
Thedrf-standardized-errors package provides an exception handler that generates the same format for all 4xx and 5xx responses. It is a drop-in replacement for the default exception handler and allows customizing the error response format without rewriting the whole exception handler. The standardized error response format is easier to document and easier to handle by API consumers.