document failed login limit

izuzak · izuzak · commit 3bd945ebd969 · 2013-12-11T18:15:35.000+01:00
diff --git a/content/v3.md b/content/v3.md
@@ -188,9 +188,9 @@ Verb | Description
 ## Authentication
 
 There are three ways to authenticate through GitHub API v3.  Requests that
-require authentication will return 404, instead of 403, in some places.  This
-is to prevent the accidental leakage of private repositories to unauthorized
-users.
+require authentication will return `404 Not Found`, instead of
+`403 Forbidden`, in some places.  This is to prevent the accidental leakage
+of private repositories to unauthorized users.
 
 ### Basic Authentication
 
@@ -224,6 +224,36 @@ This should only be used in server to server scenarios.  Don't leak your
 OAuth application's client secret to your users.  Read [more about
 unauthenticated rate limiting](#unauthenticated-rate-limited-requests).
 
+### Failed login limit
+
+Authenticating with invalid credentials will return `401 Unauthorized`:
+
+<pre class="terminal">
+$ curl -i https://api.github.com -u foo:bar
+
+HTTP/1.1 401 Unauthorized
+
+{
+  "message": "Bad credentials",
+  "documentation_url": "http://developer.github.com/v3"
+}
+</pre>
+
+After detecting several requests with invalid credentials within a short period,
+the API will temporarily reject all authentication attempts for that user
+(including ones with valid credentials) with `403 Forbidden`:
+
+<pre class="terminal">
+$ curl -i https://api.github.com -u valid_username:valid_password
+
+HTTP/1.1 403 Forbidden
+
+{
+  "message": "Maximum number of login attempts exceeded",
+  "documentation_url": "http://developer.github.com/v3"
+}
+</pre>
+
 ## Hypermedia
 
 All resources may have one or more `*_url` properties linking to other
