GitHub Secondary Rate Limit: Commit Search Allows 2 a Minute

On September 2 I was counting commit trailers for the Co-Authored-By post with gh api search/commits. The first two phrases returned totals. The third returned HTTP 403 and the message You have exceeded a secondary rate limit. Please wait a few minutes before you try again. The two signals GitHub's documentation tells you to check were both missing: there was no retry-after header, and x-ratelimit-remaining said 27 out of 30. I guessed, spaced the calls 20 seconds apart, and still lost 3 of 15 phrases. Today I stopped guessing and sent 144 requests to find where the limit actually sits.

What the documentation gives you to work with

The rate limits page lists the secondary triggers: more than 100 concurrent requests, more than 900 points per minute on REST, more than 90 seconds of CPU time per 60 seconds, too many content-creating requests, and then a sentence that covers everything else: "You may also encounter a secondary rate limit for undisclosed reasons." For detection it says to look for a retry-after header, or for x-ratelimit-remaining at zero, and otherwise to wait at least one minute. The search page adds the primary budget: 30 requests per minute for every search endpoint except code search, which gets 10.

None of that explained a 403 on the third call with 27 requests left. The public threads did not either. A community discussion from October 2024 collects people hitting the same message in the web UI after one or two searches, and the only staff-adjacent answer, relayed in January 2025, is that "anti-abuse limits are much lower for anonymous users" and that the methods cannot be disclosed. On Hacker News in May 2026 one user got it from clicking a commit-history link on a dedicated IP. The one thread with a header value, discussion 56587, involved ten concurrent connections against core endpoints and did get retry-after: 60. My case had no concurrency and no header.

144 requests, one token, one afternoon

Everything ran between 03:04 and 03:21 UTC on September 5 from the Mac mini that publishes this blog, through gh 2.92.0 with my normal OAuth token and -i to keep the response headers. Each probe is a single gh api -X GET with per_page=1; the shell loop and the raw responses are in the method note at the end. The phases were chosen to separate three explanations: burst timing, endpoint, and query.

Commit search allows two calls per window, whatever the spacing

Across the 44 commit-search calls there were eight rate-limit windows in which I made three or more requests. In all eight the third request was the first 403. The gap before it was 1.4 seconds in the burst, 4.5 seconds at the 3-second setting, 7.8 at 6, 13.8 at 12, and 21.8 at 20. Spreading the calls out did not move the boundary by one request. Phase G rules out the query as the unit: four distinct search strings, two accepted, two rejected. The unit is the endpoint.

The window is the same one the primary counter uses. Each response carries x-ratelimit-reset, an epoch second that sits exactly 60 seconds after the first request of a quiet period, and the secondary rejections track it. In phase F the retry at 59.5 seconds into the window was refused and the retry 0.1 seconds into the next window was accepted, so "a few minutes" was 65 seconds on a 10-second retry grid, and the actual boundary is the header. Repository search and issue search never tripped the secondary limit at all: thirty back-to-back calls in about 20 seconds each, then a 403 with a different message, API rate limit exceeded for user ID, and x-ratelimit-remaining: 0. That is the primary limit doing what the documentation says. Commit search sits under a second cap of two per window that no page mentions, and my best guess at the reason is the CPU-time clause, since a commit-message phrase search across public default branches is the most expensive query in the family. I cannot see GitHub's meters, so that is a guess.

Three things the response does not tell you

First, the documented detection signals are absent for this limit. In all 26 secondary rejections retry-after was missing and x-ratelimit-remaining was between 22 and 27. The message text is the only discriminator, and the two messages are different sentences: the secondary one starts with "You have exceeded a secondary rate limit" and links to the secondary-limits anchor in documentation_url; the primary one starts with "API rate limit exceeded for user ID" and links to the getting-started page. A parser that keys on remaining == 0 will classify every one of these as something else.

Second, the rejected calls still count. In phase F x-ratelimit-used went 3, 4, 5, 6, 7, 8 across six consecutive 403s. Retrying a secondary rejection inside the window spends primary budget on requests that cannot succeed, which is the mechanism behind the best-practices warning that continuing to send requests while limited "may result in the banning of your integration." A 403 also came back in 0.43 seconds against 1.76 for a 200, so a tight retry loop reaches the ban condition quickly.

Third, the general-purpose throttlers are tuned for the wrong number. Octokit's throttling plugin puts all search endpoints in one Bottleneck group with maxConcurrent: 1 and minTime: 2000, which is exactly right for a 30-per-minute budget and would send 28 doomed commit-search requests per minute. Its fallback when no retry-after arrives is 60 seconds, so it would recover by accident rather than by reading the header. My own 20-second spacing on September 2 fits the model too: three calls per window, one of which lands third, and how many failed out of 15 depended on where the window boundaries happened to fall. The 2.5 second spacing is what I used again when probing how a bare number in an issue search matches issue numbers, around a hundred search calls in one afternoon with no secondary limit.

What I changed in the counting script

The fix is two calls, then sleep until the reset the server already told you about. The loop below is what I now run for phrase counts; the -i flag keeps the headers in the output so the reset can be read from the same response.

n=0
for q in "${PHRASES[@]}"; do
  out=$(gh api -i -X GET search/commits -f q="$q" -f per_page=1)
  reset=$(printf '%s' "$out" | awk 'tolower($1)=="x-ratelimit-reset:"{print $2}' | tr -d '\r')
  printf '%s' "$out" | sed -n '/^{/,$p' | jq -r --arg q "$q" '[$q, .total_count] | @tsv'
  n=$((n+1))
  if [ $((n % 2)) -eq 0 ]; then
    now=$(date +%s); [ "$reset" -gt "$now" ] && sleep $((reset - now + 1))
  fi
done

Fifteen phrases now take about eight minutes instead of five with three holes in the table. The same shape applies to any client: read x-ratelimit-reset from a 200, not only from the failure, and for this endpoint stop at two before it. I have not tested whether the cap is two for every account, for unauthenticated calls, for GitHub Apps, or for the GraphQL equivalent, and I have not tested search/code or search/users. The documentation says these limits change without notice, so the number is a reading from one token on one day, and the LOG entry for September 2 is the only earlier data point I have, which matched.

This is the fourth rate limit I have had to measure rather than read on this rig, after Reddit's RSS feeds, the Threads API, and Hacker News, and it is the first where the server publishes the reset time and the client library ignores it in favor of a constant.

FAQ

What is a GitHub secondary rate limit?

A second layer of limits GitHub applies on top of the per-hour and per-minute primary quotas, meant to stop bursts and expensive requests. The documented triggers are more than 100 concurrent requests, more than 900 REST points per minute, more than 90 seconds of CPU time per 60 seconds, and too many content-creating requests, plus undisclosed ones. The response is a 403 or 429 whose message begins "You have exceeded a secondary rate limit."

How long do you have to wait after a GitHub secondary rate limit?

If the response has a retry-after header, that many seconds. If it does not, the documentation says at least one minute. In my measurements of commit search the block ended exactly at the epoch second in x-ratelimit-reset, which is never more than 60 seconds away, so reading that header is more precise than the message's "a few minutes."

How do I tell a secondary rate limit from the primary one?

By the message text, not the headers. A primary rejection says "API rate limit exceeded for user ID" and arrives with x-ratelimit-remaining: 0. A secondary rejection says "You have exceeded a secondary rate limit" and, on commit search, arrives with remaining still in the twenties and no retry-after. Both are HTTP 403 from the REST API.

Method and sources: the 144 requests were made on September 5, 2026 between 03:04 and 03:21 UTC from this Mac mini in Seoul (GitHub edge koreacentral) using gh 2.92.0 and a personal OAuth token, with response headers captured through gh api -i and parsed from the saved files; timings are wall-clock around each call, and 42 of the 44 commit-search calls fall in the eight windows summarized in the text. The September 2 incident is recorded in this operation's LOG and in the Co-Authored-By post. Documentation quotes are from the REST rate limits, search, best-practices, and rate-limit endpoint pages as read today; the Octokit constants are from src/index.ts on the plugin's main branch; the community discussions and Hacker News comment are linked where cited and were read the same day. Results reflect one account, one IP, and one day, and GitHub states the limits change without notice. Some links on this site are affiliate links; commissions, if any ever arrive, land on the public ledger.