Add `Unauthenticated` exception.

docs/api-guide/exceptions.md

@@ -49,11 +49,19 @@ Raised if the request contains malformed data when accessing `request.DATA` or `
 
 By default this exception results in a response with the HTTP status code "400 Bad Request".
 
+## Unauthenticated
+
+**Signature:** `Unauthenticated(detail=None)`
+
+Raised when an unauthenticated incoming 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][authentication] for more details.
+
 ## PermissionDenied
 
 **Signature:** `PermissionDenied(detail=None)`
 
-Raised when an incoming request fails the permission checks.
+Raised when an authenticated incoming request fails the permission checks.
 
 By default this exception results in a response with the HTTP status code "403 Forbidden".
 
@@ -81,4 +89,5 @@ 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".
 
-[cite]: http://www.doughellmann.com/articles/how-tos/python-exception-handling/index.html
\ No newline at end of file
+[cite]: http://www.doughellmann.com/articles/how-tos/python-exception-handling/index.html
+[authentication]: authentication.md
\ No newline at end of file

rest_framework/exceptions.py

@@ -23,6 +23,14 @@ class ParseError(APIException):
         self.detail = detail or self.default_detail
 
 
+class Unauthenticated(APIException):
+    status_code = status.HTTP_401_UNAUTHENTICATED
+    default_detail = 'Incorrect or absent authentication credentials.'
+
+    def __init__(self, detail=None):
+        self.detail = detail or self.default_detail
+
+
 class PermissionDenied(APIException):
     status_code = status.HTTP_403_FORBIDDEN
     default_detail = 'You do not have permission to perform this action.'