secondary rate limit example and guidance

Author: gal-legit

README.md

@@ -186,6 +186,24 @@ if _, ok := err.(*github.RateLimitError); ok {
 Learn more about GitHub rate limiting at
 https://docs.github.com/en/rest/rate-limit .
 
+In addition to these rate limits, GitHub imposes a secondary rate limit on all API clients.
+This rate limit prevents clients from making too many concurrent requests.
+
+To detect an API secondary rate limit error, you can check if its type is `*github.AbuseRateLimitError`:
+
+```go
+repos, _, err := client.Repositories.List(ctx, "", nil)
+if _, ok := err.(*github.AbuseRateLimitError); ok {
+	log.Println("hit secondary rate limit")
+}
+```
+
+You can use [go-github-ratelimit](https://github.com/gofri/go-github-ratelimit) to handle
+secondary rate limit sleep-and-retry for you.
+
+Learn more about GitHub secondary rate limiting at
+https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#secondary-rate-limits .
+
 ### Accepted Status ###
 
 Some endpoints may return a 202 Accepted status code, meaning that the

example/ratelimit/main.go

@@ -0,0 +1,39 @@
+// Copyright 2017 The go-github AUTHORS. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// The simple command demonstrates a simple functionality which
+// prompts the user for a GitHub username and lists all the public
+// organization memberships of the specified username.
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/gofri/go-github-ratelimit/github_ratelimit"
+	"github.com/google/go-github/v49/github"
+)
+
+func main() {
+	rateLimiter, err := github_ratelimit.NewRateLimitWaiterClient(nil)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		return
+	}
+
+	client := github.NewClient(rateLimiter)
+
+	// arbitrary usage of the client
+	username := "some-username"
+	organizations, _, err := client.Organizations.List(context.Background(), username, nil)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		return
+	}
+
+	for i, organization := range organizations {
+		fmt.Printf("%v. %v\n", i+1, organization.GetLogin())
+	}
+}