From b78872b7dbb55f1aa2d21f15fbb952f0c7156326 Mon Sep 17 00:00:00 2001
From: Tom Christie <tom@tomchristie.com>
Date: Wed, 17 Oct 2012 15:23:36 +0100
Subject: [PATCH] Use two seperate exceptions - `AuthenticationFailed`, and
 `NotAuthenticated`

Cleaner seperation of exception and resulting HTTP response.
Should result in more obvious error messages.
---
 docs/api-guide/authentication.md |  4 ++--
 docs/api-guide/exceptions.md     | 16 ++++++++++++----
 rest_framework/exceptions.py     | 12 ++++++++++--
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index 06f428c0c..3ace6519b 100644
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -156,12 +156,12 @@ Unauthenticated responses that are denied permission will result in an `HTTP 403
 
 To implement a custom authentication scheme, subclass `BaseAuthentication` and override the `.authenticate(self, request)` method.  The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise.
 
-In some circumstances instead of returning `None`, you may want to raise an `Unauthenticated` exception from the `.authenticate()` method.
+In some circumstances instead of returning `None`, you may want to raise an `AuthenticationFailed` exception from the `.authenticate()` method.
 
 Typically the approach you should take is:
 
 * If authentication is not attempted, return `None`.  Any other authentication schemes also in use will still be checked.
-* If authentication is attempted but fails, raise an `Unauthenticated` exception.  An error response will be returned immediately, without checking any other authentication schemes.
+* If authentication is attempted but fails, raise a `AuthenticationFailed` exception.  An error response will be returned immediately, without checking any other authentication schemes.
 
 You *may* also override the `.authentication_header(self, request)` method.  If implemented, it should return a string that will be used as the value of the `WWW-Authenticate` header in a `HTTP 401 Unauthorized` response.
 
diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md
index f5dff94af..c30f586a2 100644
--- a/docs/api-guide/exceptions.md
+++ b/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
+## AuthenticationFailed
 
-**Signature:** `Unauthenticated(detail=None)`
+**Signature:** `AuthenticationFailed(detail=None)`
 
-Raised when an unauthenticated incoming request fails the permission checks.
+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][authentication] for more details.
+
+## NotAuthenticated
+
+**Signature:** `NotAuthenticated(detail=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][authentication] for more details.
 
@@ -61,7 +69,7 @@ By default this exception results in a response with the HTTP status code "401 U
 
 **Signature:** `PermissionDenied(detail=None)`
 
-Raised when an authenticated incoming request fails the permission checks.
+Raised when an authenticated request fails the permission checks.
 
 By default this exception results in a response with the HTTP status code "403 Forbidden".
 
diff --git a/rest_framework/exceptions.py b/rest_framework/exceptions.py
index 2461cacdf..6ae0c95c8 100644
--- a/rest_framework/exceptions.py
+++ b/rest_framework/exceptions.py
@@ -23,9 +23,17 @@ class ParseError(APIException):
         self.detail = detail or self.default_detail
 
 
-class Unauthenticated(APIException):
+class AuthenticationFailed(APIException):
     status_code = status.HTTP_401_UNAUTHORIZED
-    default_detail = 'Incorrect or absent authentication credentials.'
+    default_detail = 'Incorrect authentication credentials.'
+
+    def __init__(self, detail=None):
+        self.detail = detail or self.default_detail
+
+
+class NotAuthenticated(APIException):
+    status_code = status.HTTP_401_UNAUTHORIZED
+    default_detail = 'Authentication credentials were not provided.'
 
     def __init__(self, detail=None):
         self.detail = detail or self.default_detail