diff --git a/cookbook/security/api_key_authentication.rst b/cookbook/security/api_key_authentication.rst
index 18027be259f..41afcb03bc4 100644
--- a/cookbook/security/api_key_authentication.rst
+++ b/cookbook/security/api_key_authentication.rst
@@ -37,6 +37,7 @@ value and then a User object is created::
     use Symfony\Component\Security\Core\Authentication\Token\PreAuthenticatedToken;
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
     use Symfony\Component\Security\Core\Exception\BadCredentialsException;
     use Symfony\Component\Security\Core\User\UserProviderInterface;
     use Symfony\Component\Security\Http\Authentication\SimplePreAuthenticatorInterface;
@@ -80,7 +81,9 @@ value and then a User object is created::
             $username = $userProvider->getUsernameForApiKey($apiKey);
 
             if (!$username) {
-                throw new AuthenticationException(
+                // CAUTION: this message will be returned to the client
+                // (so don't put any un-trusted messages / error strings here)
+                throw new CustomUserMessageAuthenticationException(
                     sprintf('API Key "%s" does not exist.', $apiKey)
                 );
             }
@@ -101,6 +104,11 @@ value and then a User object is created::
         }
     }
 
+.. versionadded:: 2.8
+    The ``CustomUserMessageAuthenticationException`` class is new in Symfony 2.8
+    and helps you return custom authentication messages. In 2.7 or earlier, throw
+    an ``AuthenticationException`` or any sub-class (you can still do this in 2.8).
+
 Once you've :ref:`configured <cookbook-security-api-key-config>` everything,
 you'll be able to authenticate by adding an apikey parameter to the query
 string, like ``http://example.com/admin/foo?apikey=37b51d194a7513e45b56f6524f2d51f2``.
@@ -291,7 +299,11 @@ you can use to create an error ``Response``.
 
         public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
         {
-            return new Response("Authentication Failed.", 403);
+            return new Response(
+                // this contains information about *why* authentication failed
+                // use it, or return your own message
+                strtr($exception->getMessageKey(), $exception->getMessageData())
+            , 403)
         }
     }
 
@@ -543,7 +555,8 @@ to see if the stored token has a valid User object that can be used::
             }
 
             if (!$username) {
-                throw new AuthenticationException(
+                // this message will be returned to the client
+                throw new CustomUserMessageAuthenticationException(
                     sprintf('API Key "%s" does not exist.', $apiKey)
                 );
             }
diff --git a/cookbook/security/custom_password_authenticator.rst b/cookbook/security/custom_password_authenticator.rst
index ca1f02775a2..d6efd122981 100644
--- a/cookbook/security/custom_password_authenticator.rst
+++ b/cookbook/security/custom_password_authenticator.rst
@@ -39,7 +39,7 @@ the user::
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
     use Symfony\Component\Security\Core\Encoder\UserPasswordEncoderInterface;
-    use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
     use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
     use Symfony\Component\Security\Core\User\UserProviderInterface;
     use Symfony\Component\Security\Http\Authentication\SimpleFormAuthenticatorInterface;
@@ -58,7 +58,9 @@ the user::
             try {
                 $user = $userProvider->loadUserByUsername($token->getUsername());
             } catch (UsernameNotFoundException $e) {
-                throw new AuthenticationException('Invalid username or password');
+                // CAUTION: this message will be returned to the client
+                // (so don't put any un-trusted messages / error strings here)
+                throw new CustomUserMessageAuthenticationException('Invalid username or password');
             }
 
             $passwordValid = $this->encoder->isPasswordValid($user, $token->getCredentials());
@@ -66,7 +68,9 @@ the user::
             if ($passwordValid) {
                 $currentHour = date('G');
                 if ($currentHour < 14 || $currentHour > 16) {
-                    throw new AuthenticationException(
+                    // CAUTION: this message will be returned to the client
+                    // (so don't put any un-trusted messages / error strings here)
+                    throw new CustomUserMessageAuthenticationException(
                         'You can only log in between 2 and 4!',
                         100
                     );
@@ -80,7 +84,9 @@ the user::
                 );
             }
 
-            throw new AuthenticationException('Invalid username or password');
+            // CAUTION: this message will be returned to the client
+            // (so don't put any un-trusted messages / error strings here)
+            throw new CustomUserMessageAuthenticationException('Invalid username or password');
         }
 
         public function supportsToken(TokenInterface $token, $providerKey)
@@ -95,6 +101,11 @@ the user::
         }
     }
 
+.. versionadded:: 2.8
+    The ``CustomUserMessageAuthenticationException`` class is new in Symfony 2.8
+    and helps you return custom authentication messages. In 2.7 or earlier, throw
+    an ``AuthenticationException`` or any sub-class (you can still do this in 2.8).
+
 How it Works
 ------------