encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2024-11-15 14:17:22 +03:00
Code Issues Packages Projects Releases Wiki Activity
330c13296d
django-rest-framework/api-guide/exceptions/index.html
Tom Christie 330c13296d Update documentation
2014-11-25 16:04:38 +00:00

565 lines
22 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Exceptions - Django REST framework</title>
<link href="../../img/favicon.ico" rel="icon" type="image/x-icon">
<link rel="canonical" href="http://www.django-rest-framework.org/api-guide/exceptions/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, Exceptions">
<meta name="author" content="Tom Christie">
<!-- Le styles -->
<link href="../../css/prettify.css" rel="stylesheet">
<link href="../../css/bootstrap.css" rel="stylesheet">
<link href="../../css/bootstrap-responsive.css" rel="stylesheet">
<link href="../../css/default.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-18852272-2']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script');
ga.type = 'text/javascript';
ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
})();
</script>
<style>
span.fusion-wrap a {
display: block;
margin-top: 10px;
color: black;
}
a.fusion-poweredby {
display: block;
margin-top: 10px;
}
@media (max-width: 767px) {
div.promo {
display: none;
}
}
</style>
</head>
<body onload="prettyPrint()" class="-page">
<div class="wrapper">
<div class="navbar navbar-inverse navbar-fixed-top">
<div class="navbar-inner">
<div class="container-fluid">
<a class="repo-link btn btn-primary btn-small" href="https://github.com/tomchristie/django-rest-framework/tree/master">GitHub</a>
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../status-codes">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../reverse">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="http://www.django-rest-framework.org">Django REST framework</a>
<div class="nav-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li ><a href="/">Home</a></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../../tutorial/quickstart">Quickstart</a>
</li>
<li >
<a href="../../tutorial/1-serialization">1 - Serialization</a>
</li>
<li >
<a href="../../tutorial/2-requests-and-responses">2 - Requests and responses</a>
</li>
<li >
<a href="../../tutorial/3-class-based-views">3 - Class based views</a>
</li>
<li >
<a href="../../tutorial/4-authentication-and-permissions">4 - Authentication and permissions</a>
</li>
<li >
<a href="../../tutorial/5-relationships-and-hyperlinked-apis">5 - Relationships and hyperlinked APIs</a>
</li>
<li >
<a href="../../tutorial/6-viewsets-and-routers">6- Viewsets and routers</a>
</li>
</ul>
</li>
<li class="dropdown active">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Guide <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../requests">Requests</a>
</li>
<li >
<a href="../responses">Responses</a>
</li>
<li >
<a href="../views">Views</a>
</li>
<li >
<a href="../generic-views">Generic views</a>
</li>
<li >
<a href="../viewsets">Viewsets</a>
</li>
<li >
<a href="../routers">Routers</a>
</li>
<li >
<a href="../parsers">Parsers</a>
</li>
<li >
<a href="../renderers">Renderers</a>
</li>
<li >
<a href="../serializers">Serializers</a>
</li>
<li >
<a href="../fields">Serializer fields</a>
</li>
<li >
<a href="../relations">Serializer relations</a>
</li>
<li >
<a href="../validators">Validators</a>
</li>
<li >
<a href="../authentication">Authentication</a>
</li>
<li >
<a href="../permissions">Permissions</a>
</li>
<li >
<a href="../throttling">Throttling</a>
</li>
<li >
<a href="../filtering">Filtering</a>
</li>
<li >
<a href="../pagination">Pagination</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
<li >
<a href="../format-suffixes">Format suffixes</a>
</li>
<li >
<a href="../reverse">Returning URLs</a>
</li>
<li class="active" >
<a href=".">Exceptions</a>
</li>
<li >
<a href="../status-codes">Status codes</a>
</li>
<li >
<a href="../testing">Testing</a>
</li>
<li >
<a href="../settings">Settings</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Topics <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../../topics/documenting-your-api">Documenting your API</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/browser-enhancements">Browser enhancements</a>
</li>
<li >
<a href="../../topics/browsable-api">The Browsable API</a>
</li>
<li >
<a href="../../topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a>
</li>
<li >
<a href="../../topics/third-party-resources">Third Party Resources</a>
</li>
<li >
<a href="../../topics/contributing">Contributing to REST framework</a>
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement">Kickstarter Announcement</a>
</li>
<li >
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
</ul>
</div>
<!--/.nav-collapse -->
</div>
</div>
</div>
<div class="body-content">
<div class="container-fluid">
<!-- Search Modal -->
<div id="searchModal" class="modal hide fade" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
<h3 id="myModalLabel">Documentation search</h3>
</div>
<div class="modal-body">
<!-- Custom google search -->
<script>
(function() {
var cx = '015016005043623903336:rxraeohqk6w';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
'//www.google.com/cse/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
</script>
<gcse:search></gcse:search>
</div>
<div class="modal-footer">
<button class="btn" data-dismiss="modal" aria-hidden="true">Close</button>
</div>
</div>
<div class="row-fluid">
<div class="span3">
<!-- TODO
<p style="margin-top: -12px">
<a class="btn btn-mini btn-primary" style="width: 60px">&laquo; previous</a>
<a class="btn btn-mini btn-primary" style="float: right; margin-right: 8px; width: 60px;">next &raquo;</a>
</p>
-->
<div id="table-of-contents">
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
<li class="main">
<a href="#exceptions">Exceptions</a>
</li>
<li>
<a href="#exception-handling-in-rest-framework-views">Exception handling in REST framework views</a>
</li>
<li>
<a href="#custom-exception-handling">Custom exception handling</a>
</li>
<li class="main">
<a href="#api-reference">API Reference</a>
</li>
<li>
<a href="#apiexception">APIException</a>
</li>
<li>
<a href="#parseerror">ParseError</a>
</li>
<li>
<a href="#authenticationfailed">AuthenticationFailed</a>
</li>
<li>
<a href="#notauthenticated">NotAuthenticated</a>
</li>
<li>
<a href="#permissiondenied">PermissionDenied</a>
</li>
<li>
<a href="#methodnotallowed">MethodNotAllowed</a>
</li>
<li>
<a href="#unsupportedmediatype">UnsupportedMediaType</a>
</li>
<li>
<a href="#throttled">Throttled</a>
</li>
</ul>
</div>
</div>
<div id="main-content" class="span9">
<a class="github" href="https://github.com/tomchristie/django-rest-framework/tree/master/rest_framework/exceptions.py">
<span class="label label-info">exceptions.py</span>
</a>
<h1 id="exceptions">Exceptions</h1>
<blockquote>
<p>Exceptions… allow error handling to be organized cleanly in a central or high-level place within the program structure.</p>
<p>&mdash; Doug Hellmann, <a href="http://www.doughellmann.com/articles/how-tos/python-exception-handling/index.html">Python Exception Handling Techniques</a></p>
</blockquote>
<h2 id="exception-handling-in-rest-framework-views">Exception handling in REST framework views</h2>
<p>REST framework's views handle various exceptions, and deal with returning appropriate error responses.</p>
<p>The handled exceptions are:</p>
<ul>
<li>Subclasses of <code>APIException</code> raised inside REST framework.</li>
<li>Django's <code>Http404</code> exception.</li>
<li>Django's <code>PermissionDenied</code> exception.</li>
</ul>
<p>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.</p>
<p>By default all error responses will include a key <code>detail</code> in the body of the response, but other keys may also be included.</p>
<p>For example, the following request:</p>
<pre><code>DELETE http://api.example.com/foo/bar HTTP/1.1
Accept: application/json
</code></pre>
<p>Might receive an error response indicating that the <code>DELETE</code> method is not allowed on that resource:</p>
<pre><code>HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 42
{"detail": "Method 'DELETE' not allowed."}
</code></pre>
<h2 id="custom-exception-handling">Custom exception handling</h2>
<p>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.</p>
<p>The function must take a single argument, which is the exception to be handled, and should either return a <code>Response</code> object, or return <code>None</code> if the exception cannot be handled. If the handler returns <code>None</code> then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.</p>
<p>For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:</p>
<pre><code>HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 62
{"status_code": 405, "detail": "Method 'DELETE' not allowed."}
</code></pre>
<p>In order to alter the style of the response, you could write the following custom exception handler:</p>
<pre><code>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
</code></pre>
<p>The exception handler must also be configured in your settings, using the <code>EXCEPTION_HANDLER</code> setting key. For example:</p>
<pre><code>REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
}
</code></pre>
<p>If not specified, the <code>'EXCEPTION_HANDLER'</code> setting defaults to the standard exception handler provided by REST framework:</p>
<pre><code>REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}
</code></pre>
<p>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 <code>HTTP_400_BAD_REQUEST</code> responses that are returned by the generic views when serializer validation fails.</p>
<hr />
<h1 id="api-reference">API Reference</h1>
<h2 id="apiexception">APIException</h2>
<p><strong>Signature:</strong> <code>APIException()</code></p>
<p>The <strong>base class</strong> for all exceptions raised inside an <code>APIView</code> class or <code>@api_view</code>.</p>
<p>To provide a custom exception, subclass <code>APIException</code> and set the <code>.status_code</code> and <code>.default_detail</code> properties on the class.</p>
<p>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:</p>
<pre><code>from rest_framework.exceptions import APIException
class ServiceUnavailable(APIException):
status_code = 503
default_detail = 'Service temporarily unavailable, try again later.'
</code></pre>
<h2 id="parseerror">ParseError</h2>
<p><strong>Signature:</strong> <code>ParseError(detail=None)</code></p>
<p>Raised if the request contains malformed data when accessing <code>request.DATA</code> or <code>request.FILES</code>.</p>
<p>By default this exception results in a response with the HTTP status code "400 Bad Request".</p>
<h2 id="authenticationfailed">AuthenticationFailed</h2>
<p><strong>Signature:</strong> <code>AuthenticationFailed(detail=None)</code></p>
<p>Raised when an incoming request includes incorrect authentication.</p>
<p>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 <a href="../authentication">authentication documentation</a> for more details.</p>
<h2 id="notauthenticated">NotAuthenticated</h2>
<p><strong>Signature:</strong> <code>NotAuthenticated(detail=None)</code></p>
<p>Raised when an unauthenticated request fails the permission checks.</p>
<p>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 <a href="../authentication">authentication documentation</a> for more details.</p>
<h2 id="permissiondenied">PermissionDenied</h2>
<p><strong>Signature:</strong> <code>PermissionDenied(detail=None)</code></p>
<p>Raised when an authenticated request fails the permission checks.</p>
<p>By default this exception results in a response with the HTTP status code "403 Forbidden".</p>
<h2 id="methodnotallowed">MethodNotAllowed</h2>
<p><strong>Signature:</strong> <code>MethodNotAllowed(method, detail=None)</code></p>
<p>Raised when an incoming request occurs that does not map to a handler method on the view.</p>
<p>By default this exception results in a response with the HTTP status code "405 Method Not Allowed".</p>
<h2 id="unsupportedmediatype">UnsupportedMediaType</h2>
<p><strong>Signature:</strong> <code>UnsupportedMediaType(media_type, detail=None)</code></p>
<p>Raised if there are no parsers that can handle the content type of the request data when accessing <code>request.DATA</code> or <code>request.FILES</code>.</p>
<p>By default this exception results in a response with the HTTP status code "415 Unsupported Media Type".</p>
<h2 id="throttled">Throttled</h2>
<p><strong>Signature:</strong> <code>Throttled(wait=None, detail=None)</code></p>
<p>Raised when an incoming request fails the throttling checks.</p>
<p>By default this exception results in a response with the HTTP status code "429 Too Many Requests".</p>
</div>
<!--/span-->
</div>
<!--/row-->
</div>
<!--/.fluid-container-->
</div>
<!--/.body content-->
<div id="push"></div>
</div>
<!--/.wrapper -->
<footer class="span12">
<p>Sponsored by <a href="http://dabapps.com/">DabApps</a>.</a>
</p>
</footer>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="../../js/jquery-1.8.1-min.js"></script>
<script src="../../js/prettify-1.0.js"></script>
<script src="../../js/bootstrap-2.1.1-min.js"></script>
<script>
//$('.side-nav').scrollspy()
var shiftWindow = function() {
scrollBy(0, -50)
};
if (location.hash) shiftWindow();
window.addEventListener("hashchange", shiftWindow);
$('.dropdown-menu').on('click touchstart', function(event) {
event.stopPropagation();
});
// Dynamically force sidenav to no higher than browser window
$('.side-nav').css('max-height', window.innerHeight - 130);
$(function() {
$(window).resize(function() {
$('.side-nav').css('max-height', window.innerHeight - 130);
});
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink