docs(throttling): clarify return values and reduce unnecessary rateli…

…mit fails (#1849)

docs/src/pages/api/09_throttling.md

@@ -6,7 +6,9 @@ When you send too many requests in too little time you will likely hit errors du
 
 In order to automatically throttle requests as recommended in [GitHub’s best practices for integrators](https://developer.github.com/v3/guides/best-practices-for-integrators/), we recommend you install the [`@octokit/plugin-throttling` plugin](https://github.com/octokit/plugin-throttling.js).
 
-The `throttle.onAbuseLimit` and `throttle.onRateLimit` options are required. Return `true` to automatically retry the request after `retryAfter` seconds.
+The `throttle.onAbuseLimit` and `throttle.onRateLimit` options are required.
+
+Return `true` from these functions to automatically retry the request after `retryAfter` seconds. Return `false` or `undefined` to skip retry and throw the error. For rate limit errors, `retryAfter` defaults to seconds until `X-RateLimit-Reset`. For abuse errors, `retryAfter` defaults to the `retry-after` header but is a minimum of five seconds.
 
 ```js
 const { Octokit } = require("@octokit/rest");
@@ -21,8 +23,8 @@ const octokit = new MyOctokit({
         `Request quota exhausted for request ${options.method} ${options.url}`
       );
 
-      if (options.request.retryCount === 0) {
-        // only retries once
+      // Retry twice after hitting a rate limit error, then give up
+      if (options.request.retryCount <= 2) {
         console.log(`Retrying after ${retryAfter} seconds!`);
         return true;
       }