Old question, but I hope this helps someone in the future. The accepted answer doesn’t really answer the original question…
You can do this with django rest framework easily by raising ApiException:
from rest_framework.exceptions import APIException
try:
...
except ...:
raise APIException('custom exception message')
This will return a response with status 500 from your view. Pretty useful if you are calling another function from your API and you don’t want to manage return values from this function to decide if returning a response with status 500.
You can use it like this:
raise ApiException
And the default response message (at the time of writing this) will be ‘A server error occurred.’.
There’s a few predefined ApiException subclasses to raise different kinds of errors, check the file rest_framework.exceptions, if you need one that is not in there, you can extend ApiException like this:
from rest_framework.exceptions import APIException
class YourCustomApiExceptionName(APIException):
def __init__(self, status, detail):
self.status_code = status
self.detail = detail
Usage:
raise YourCustomApiExceptionName(100, 'continue')
You can also define custom status and detail but wouldn’t make much sense in most cases.
EDIT:
If for some reason you are working without DRF, you can just copy the APIException code instead of installing the DRF package:
https://github.com/encode/django-rest-framework/blob/4f7e9ed3bbb0fb3567884ef4e3d340bc2f77bc68/rest_framework/exceptions.py#L99
exceptions.py
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
Exception handling in REST framework views
REST framework’s views handle various exceptions, and deal with returning appropriate error responses.
The handled exceptions are:
- Subclasses of
APIException
raised inside REST framework. - Django’s
Http404
exception. - Django’s
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 key detail
in the body of the response.
For example, the following request:
DELETE http://api.example.com/foo/bar HTTP/1.1
Accept: application/json
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
Content-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 the NON_FIELD_ERRORS_KEY
setting.
An example validation error might look like this:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 94
{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}
Custom exception handling
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 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.
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 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, 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 response
The 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 as context['view']
.
The exception handler must also be configured in your settings, using the EXCEPTION_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 the HTTP_400_BAD_REQUEST
responses that are returned by the generic views when serializer validation fails.
API Reference
APIException
Signature: APIException()
The base class for all exceptions raised inside an APIView
class or @api_view
.
To provide a custom exception, subclass APIException
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 APIException
class ServiceUnavailable(APIException):
status_code = 503
default_detail = 'Service temporarily unavailable, try again later.'
default_code = 'service_unavailable'
Inspecting API exceptions
There are a number of different properties available for inspecting the status
of an API exception. You can use these to build custom exception handling
for 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 or
dictionary 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"}}
ParseError
Signature: ParseError(detail=None, code=None)
Raised if the request contains malformed data when accessing request.data
.
By default this exception results in a response with the HTTP status code «400 Bad Request».
AuthenticationFailed
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 the authentication documentation for more details.
NotAuthenticated
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 the authentication documentation for more details.
PermissionDenied
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».
NotFound
Signature: NotFound(detail=None, code=None)
Raised when a resource does not exists at the given URL. This exception is equivalent to the standard Http404
Django exception.
By default this exception results in a response with the HTTP status code «404 Not Found».
MethodNotAllowed
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».
NotAcceptable
Signature: NotAcceptable(detail=None, code=None)
Raised when an incoming request occurs with an Accept
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 accessing request.data
.
By default this exception results in a response with the HTTP status code «415 Unsupported Media Type».
Throttled
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».
ValidationError
Signature: ValidationError(detail, code=None)
The ValidationError
exception is slightly different from the other APIException
classes:
- The
detail
argument is mandatory, not optional. - The
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.'})
- By convention you should import the serializers module and use a fully qualified
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.')
The ValidationError
class should be used for serializer and field validation, and by validator classes. It is also raised when calling serializer.is_valid
with the raise_exception
keyword argument:
serializer.is_valid(raise_exception=True)
The generic views use the raise_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».
Generic Error Views
Django REST Framework provides two error views suitable for providing generic JSON 500
Server Error and
400
Bad Request responses. (Django’s default error views provide HTML responses, which may not be appropriate for an
API-only application.)
Use these as per Django’s Customizing error views documentation.
rest_framework.exceptions.server_error
Returns a response with status code 500
and application/json
content type.
Set as handler500
:
handler500 = 'rest_framework.exceptions.server_error'
rest_framework.exceptions.bad_request
Returns a response with status code 400
and application/json
content type.
Set as handler400
:
handler400 = 'rest_framework.exceptions.bad_request'
Third party packages
The following third-party packages are also available.
DRF Standardized Errors
The drf-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.
-
Getting Help
-
el
-
es
-
fr
-
id
-
it
-
ja
-
ko
-
pl
-
pt-br
-
zh-hans
- Language: en
-
1.8
-
1.10
-
1.11
-
2.0
-
2.1
-
2.2
-
3.0
-
3.1
-
3.2
-
4.0
-
4.1
-
5.0
-
dev
-
Documentation version:
4.2
Built-in Views¶
Several of Django’s built-in views are documented in
Writing views as well as elsewhere in the documentation.
Serving files in development¶
-
static.
serve
(request, path, document_root, show_indexes=False)¶
There may be files other than your project’s static assets that, for
convenience, you’d like to have Django serve for you in local development.
The serve()
view can be used to serve any directory
you give it. (This view is not hardened for production use and should be
used only as a development aid; you should serve these files in production
using a real front-end web server).
The most likely example is user-uploaded content in MEDIA_ROOT
.
django.contrib.staticfiles
is intended for static assets and has no
built-in handling for user-uploaded files, but you can have Django serve your
MEDIA_ROOT
by appending something like this to your URLconf:
from django.conf import settings from django.urls import re_path from django.views.static import serve # ... the rest of your URLconf goes here ... if settings.DEBUG: urlpatterns += [ re_path( r"^media/(?P<path>.*)$", serve, { "document_root": settings.MEDIA_ROOT, }, ), ]
Note, the snippet assumes your MEDIA_URL
has a value of
'media/'
. This will call the serve()
view,
passing in the path from the URLconf and the (required) document_root
parameter.
Since it can become a bit cumbersome to define this URL pattern, Django
ships with a small URL helper function static()
that takes as parameters the prefix such as MEDIA_URL
and a dotted
path to a view, such as 'django.views.static.serve'
. Any other function
parameter will be transparently passed to the view.
Error views¶
Django comes with a few views by default for handling HTTP errors. To override
these with your own custom views, see Customizing error views.
The 404 (page not found) view¶
-
defaults.
page_not_found
(request, exception, template_name=‘404.html’)¶
When you raise Http404
from within a view, Django loads a
special view devoted to handling 404 errors. By default, it’s the view
django.views.defaults.page_not_found()
, which either produces a “Not
Found” message or loads and renders the template 404.html
if you created it
in your root template directory.
The default 404 view will pass two variables to the template: request_path
,
which is the URL that resulted in the error, and exception
, which is a
useful representation of the exception that triggered the view (e.g. containing
any message passed to a specific Http404
instance).
Three things to note about 404 views:
- The 404 view is also called if Django doesn’t find a match after
checking every regular expression in the URLconf. - The 404 view is passed a
RequestContext
and
will have access to variables supplied by your template context
processors (e.g.MEDIA_URL
). - If
DEBUG
is set toTrue
(in your settings module), then
your 404 view will never be used, and your URLconf will be displayed
instead, with some debug information.
The 500 (server error) view¶
-
defaults.
server_error
(request, template_name=‘500.html’)¶
Similarly, Django executes special-case behavior in the case of runtime errors
in view code. If a view results in an exception, Django will, by default, call
the view django.views.defaults.server_error
, which either produces a
“Server Error” message or loads and renders the template 500.html
if you
created it in your root template directory.
The default 500 view passes no variables to the 500.html
template and is
rendered with an empty Context
to lessen the chance of additional errors.
If DEBUG
is set to True
(in your settings module), then
your 500 view will never be used, and the traceback will be displayed
instead, with some debug information.
The 403 (HTTP Forbidden) view¶
-
defaults.
permission_denied
(request, exception, template_name=‘403.html’)¶
In the same vein as the 404 and 500 views, Django has a view to handle 403
Forbidden errors. If a view results in a 403 exception then Django will, by
default, call the view django.views.defaults.permission_denied
.
This view loads and renders the template 403.html
in your root template
directory, or if this file does not exist, instead serves the text
“403 Forbidden”, as per RFC 9110#section-15.5.4 (the HTTP 1.1
Specification). The template context contains exception
, which is the
string representation of the exception that triggered the view.
django.views.defaults.permission_denied
is triggered by a
PermissionDenied
exception. To deny access in a
view you can use code like this:
from django.core.exceptions import PermissionDenied def edit(request, pk): if not request.user.is_staff: raise PermissionDenied # ...
The 400 (bad request) view¶
-
defaults.
bad_request
(request, exception, template_name=‘400.html’)¶
When a SuspiciousOperation
is raised in Django,
it may be handled by a component of Django (for example resetting the session
data). If not specifically handled, Django will consider the current request a
‘bad request’ instead of a server error.
django.views.defaults.bad_request
, is otherwise very similar to the
server_error
view, but returns with the status code 400 indicating that
the error condition was the result of a client operation. By default, nothing
related to the exception that triggered the view is passed to the template
context, as the exception message might contain sensitive information like
filesystem paths.
bad_request
views are also only used when DEBUG
is False
.
Back to Top
When building a web application, it’s important to provide a seamless and user-friendly experience even when things go wrong. One common issue that users might encounter is the “500 Internal Server Error.” While this error can be caused by a variety of server-side issues, you can still make the error experience more pleasant by creating a custom 500 error template. In this tutorial, we’ll walk you through the steps to implement a custom 500 error template in your Django project.
Why Create a Custom 500 Error Template?
The “500 Internal Server Error” is a generic error message that indicates a problem on the server’s end. Instead of showing users a technical error page, you can use a custom template to provide a friendlier message and reassure users that the issue is being looked into. A custom 500 error page can maintain your website’s branding, offer helpful information, and keep users engaged even in error scenarios.
Let’s dive into the process of creating and implementing a custom 500 error template in your Django project.
Step 1: Creating the Custom 500 Error Template
- In your Django project, navigate to the
templates
directory within your app’s main directory. - Create a new subdirectory named
500
(matching the HTTP error code) inside thetemplates
directory. - Inside the
500
directory, create a file named500.html
. This file will contain the content of your custom 500 error page.
Step 2: Creating the Custom 500 Template
- In your Django project, navigate to the
templates
directory. If it doesn’t exist, create it within your app’s main directory. - Inside the
templates
directory, create a file named500.html
. This file will contain the content of your custom 500 error page.
Step 3: Designing Your Custom 500 Error Page
Design your custom 500 error page just like you would for any other web page. You can use HTML, CSS, and even JavaScript to create an appealing and informative error page. Here’s an example of what your 500.html
file might look like:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>500 Internal Server Error</title>
<style>
/* Your custom CSS styles go here */
body {
font-family: Arial, sans-serif;
background-color: #f3f3f3;
}
.container {
text-align: center;
padding: 100px;
}
h1 {
font-size: 48px;
color: #ff5733;
}
p {
font-size: 18px;
color: #555;
}
</style>
</head>
<body>
<div class="container">
<h1>Oops! Something Went Wrong</h1>
<p>We're experiencing technical difficulties. Please try again later.</p>
<p>If the issue persists, you can contact our support team at [email protected].</p>
</div>
</body>
</html>
Step 4: Custom 500 View for Django handler500
Create a new view in one of your app’s views files. For example, if your app is named yourapp
, you can create a view function in views.py
:
from django.shortcuts import render
def custom_500(request):
return render(request, '500.html', status=500)
Replace 'yourapp'
with the actual name of your app.
Step 5: Updating Django Settings
To make Django use your custom 500 error page, you need to update the handler500
view in your project’s urls.py
file.
- Open your project’s
urls.py
file. - Add the following line to your URL patterns, before the
urlpatterns
list:
from django.conf.urls import handler500
handler500 = 'yourapp.views.custom_500'
NOTE: If your project is running in DEBUG
mode, then you will not see the page, you need to update Debug Mode and ALLOWED_HOST
in settings.py
file, like bellow:
DEBUG = False
ALLOWED_HOSTS = ['*']
Step 6: Testing Your Custom 500 Error Page
To test your custom 500 error page:
- Start your Django development server.
- Simulate a server error (e.g., by intentionally causing an exception in your code). Example:
def hello_world(request): raise Exception('This is a test error')
- Instead of the default technical error page, you should now see your custom 500 error page, providing users with a more user-friendly experience.
Conclusion
By creating and implementing a custom 500 error template in your Django project, you can ensure that users are greeted with a friendly and informative message even when encountering server errors. This simple effort can contribute to a better overall user experience and help maintain engagement with your website. Follow the steps in this guide to create a seamless error experience that aligns with your website’s design and branding.
Find this tutorial on Github.
Blogs You Might Like to Read!
- Custom 404 Error Page Template in Django with Example
- Mastering Django Templates: Guide with Examples
- Folder and File Structure for Django Templates: Best Practices
- Django Bootstrap – Integrate Template Example
- Django Crispy Forms and Bootstrap 5
- Best Folder and Directory Structure for a Django Project
- Django Rest Framework Tutorials
When developing a Django web application, it is important to test the error pages to ensure that they display correctly when an error occurs. In particular, the 500 error page (also known as the Internal Server Error page) is a crucial component that should be tested to ensure that users receive a helpful and informative response when something goes wrong on the server side. In this article, we will look at a few methods for testing the 500.html error page in a Django development environment.
Method 1: Raise a 500 error in views.py
To raise a 500 error in Django and test the error page, follow these steps:
- In your
views.py
file, create a view function that raises a500
error:
from django.http import HttpResponseServerError
def test_500_error(request):
raise HttpResponseServerError()
- In your
urls.py
file, map a URL to the view function:
from django.urls import path
from . import views
urlpatterns = [
path('test-500-error/', views.test_500_error),
]
- Start your Django development server:
python manage.py runserver
- Open your web browser and navigate to the URL you mapped in step 2:
http://localhost:8000/test-500-error/
- Django should raise a
500
error and display the error page. Verify that the error page is displayed correctly.
That’s it! You have successfully raised a 500
error in Django and tested the error page.
Method 2: Manually trigger a 500 error
To manually trigger a 500 error in Django development environment, you can use the django.views.defaults.server_error
view. This view raises an Exception
to simulate a server error and render the 500.html
template.
Here are the steps to manually trigger a 500 error:
- Import the
server_error
view fromdjango.views.defaults
:
from django.views.defaults import server_error
- Create a view that calls the
server_error
view:
def trigger_500(request):
response = server_error(request)
return response
- Add a URL pattern for the
trigger_500
view in yoururls.py
:
from django.urls import path
from . import views
urlpatterns = [
# ... other URL patterns ...
path('trigger-500/', views.trigger_500, name='trigger_500'),
]
- Visit the
/trigger-500/
URL in your browser to trigger the 500 error and see the500.html
template.
That’s it! By following these steps, you can manually trigger a 500 error in Django development environment and test your 500.html
template.
Method 3: Use Django’s TestClient to simulate a 500 error
To simulate a 500 error using Django’s TestClient, you can follow these steps:
- Import the necessary modules:
from django.test import TestCase, Client
from django.urls import reverse
- Define a test case that inherits from
django.test.TestCase
:
class Test500Error(TestCase):
def setUp(self):
self.client = Client()
- Define a test method that uses the
client
to simulate a 500 error:
def test_500_error(self):
response = self.client.get(reverse('500_error_view'))
self.assertEqual(response.status_code, 500)
- Define a view that raises an exception to trigger the 500 error:
def error_view(request):
raise Exception('Test 500 error')
- Define a URL pattern that maps to the
error_view
:
urlpatterns = [
path('500-error/', error_view, name='500_error_view'),
]
- Run the test case to verify that the
client
returns a 500 error:
python manage.py test app.tests.Test500Error
Here’s the complete code:
from django.test import TestCase, Client
from django.urls import reverse
def error_view(request):
raise Exception('Test 500 error')
class Test500Error(TestCase):
def setUp(self):
self.client = Client()
def test_500_error(self):
response = self.client.get(reverse('500_error_view'))
self.assertEqual(response.status_code, 500)
urlpatterns = [
path('500-error/', error_view, name='500_error_view'),
]
python manage.py test app.tests.Test500Error