When a GitHub API request fails with 403 or 429, inspect the response headers and body before retrying: the status code alone does not tell you how long to wait. Honor retry-after if present; otherwise, use the primary-limit reset time when the remaining count is zero, or pause and back off for a secondary-limit failure. In an agent workflow, coordinate requests across workers, then diagnose failed Actions jobs before deciding whether to rerun them.
Which GitHub limits can affect an agent workflow?
GitHub applies primary rate limits according to authentication type and the API resource being accessed. For the common GitHub Actions case, GitHub documents a limit of 1,000 requests per hour per repository for the built-in GITHUB_TOKEN. For requests to resources that belong to GitHub Enterprise Cloud accounts, the documented limit is 15,000 requests per hour per repository. These are current documentation values, not permanent guarantees; check GitHub’s live documentation because limits can change.
Secondary limits are separate from the primary hourly budget. They can be triggered by request concurrency, points, compute consumption, content creation, or other conditions GitHub does not disclose. GitHub currently documents a maximum of 100 concurrent REST and GraphQL requests combined, 900 points per minute for REST endpoints, and 2,000 points per minute for the GraphQL endpoint. Limits can be lower for some endpoints and may change without notice.
Primary exhaustion versus secondary throttling
| What happened | What the client can observe | What to do |
|---|---|---|
| Primary rate limit exhausted | x-ratelimit-remaining: 0, with a reset time in x-ratelimit-reset |
Wait until the reset time, unless retry-after specifies a longer wait. |
| Secondary rate limit triggered | Usually a 403 or 429 response with an explanatory message; remaining primary allowance may not be zero |
Honor retry-after if present. Otherwise pause at least one minute, then increase the wait between repeated failures. |
| Authentication or permission problem | A request is denied even though the primary budget is not exhausted; a 403 or 404 can also reflect access boundaries |
Check the token, repository, and permissions before treating the error as transient. |
GitHub’s REST response headers are the live signal for a request’s primary-limit status. They include the limit, remaining count, used count, reset time as UTC epoch seconds, and resource family. Values may vary because requests can be processed across regions, so use them to pace requests rather than assuming the remaining count will be exact.
#1 Best Overall
GET /rate_limit can provide a periodic overview by resource family and does not consume primary allowance. It may, however, count against secondary limits, and its summary can disagree with response headers. GitHub does not provide an endpoint that directly reports secondary-limit status.
How should a client retry a rate-limited API request?
GitHub documents rate-limit errors as 403 Forbidden or 429 Too Many Requests. Inspect both the response headers and body; do not choose a wait strategy from the status code alone. Apply the following order:
- If the response includes
retry-after, wait at least the stated number of seconds before retrying. - Otherwise, if
x-ratelimit-remainingis0, wait until the UTC epoch time inx-ratelimit-reset. - Otherwise, wait at least one minute before retrying.
- If secondary-limit failures continue, increase the delay exponentially between attempts and stop after a defined retry count.
GitHub’s REST API troubleshooting guidance recommends exponentially increasing waits for continued secondary-limit failures and throwing an error after a specific number of retries. Continuing to send requests while limited risks an integration ban. Make the retry cap explicit and return a useful error when it is reached, rather than retrying forever.
Before repeating a request that changes data, consider whether the operation is safe to repeat. That is an engineering safeguard, not a promise from GitHub’s rate-limit guidance: a retry may repeat a mutation if the first attempt succeeded but its response was lost. Preserve the original response headers and error body in logs so the scheduler and operator can distinguish throttling from a permission or application failure.
Rank #3
How can multiple agents avoid throttling one another?
GitHub recommends authenticated API calls, serial requests to avoid secondary limits, and at least a one-second pause between large numbers of mutative requests such as POST, PATCH, PUT, and DELETE. Authentication generally provides a higher primary limit, but it does not remove secondary limits.
Coordinate at the shared credential boundary
When several workers use the same credential, each worker’s local request rate can look modest while their combined traffic exceeds a limit. A shared queue or rate limiter is a practical way to serialize requests and apply server-provided reset timing across workers. This is an implementation pattern inferred from GitHub’s serialization advice; GitHub does not prescribe a particular scheduler design.
Rank #4
- Group requests by credential and API resource where practical.
- Feed
retry-afterand primary reset timing back into the shared scheduler, not just the worker that received the error. - Keep concurrency bounded across REST and GraphQL calls made by the workflow.
- Apply the one-second pause when issuing large numbers of mutative requests.
Use a token with the right access
In Actions, use GITHUB_TOKEN when it has the access the workflow needs, and grant only necessary permissions with the workflow’s permissions key. The token applies to repository-owned resources where the workflow runs; accessing another repository or organization may require a different authorized credential, such as a GitHub App token or personal access token. Check authentication and permissions before interpreting a 403 or 404 as a rate-limit failure.
When should you rerun a GitHub Actions workflow?
An API retry and an Actions rerun recover different things. Retry an individual API operation when the request was throttled and the operation is safe to repeat. Rerun a workflow only after inspecting its logs and deciding that repeating the relevant job or run is the right recovery action.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Diagnose the failed run first
Open the run’s logs to identify the failed step; GitHub Actions logs can also be searched or downloaded. Determine whether the failure came from a transient API limit, a code or configuration error, or missing authorization. Replaying unchanged work will not fix a persistent permissions or logic problem.
Job dependencies matter: jobs that need a failed or skipped job are skipped unless their conditions explicitly allow them to continue. Use conditions deliberately for cleanup or reporting tasks, and verify that those conditions do not unintentionally keep work running after cancellation.
Choose the smallest useful rerun scope
| Recovery action | When it fits | GitHub CLI |
|---|---|---|
| Rerun failed jobs | The failure is confined to failed jobs and their work can safely be repeated. | gh run rerun RUN_ID --failed |
| Rerun a selected job | You have identified one job that needs another attempt. | gh run rerun RUN_ID --job JOB_ID |
| Rerun the workflow | The run needs to execute again more broadly than the failed jobs or a selected job. | gh run rerun RUN_ID |
GitHub allows reruns for up to 30 days after the initial run and caps a workflow run at 50 reruns. A rerun uses the privileges of the actor who first triggered the workflow and retains the original event’s GITHUB_SHA and GITHUB_REF; it does not start a new run against the latest commit.
How do you prevent overlapping workflow side effects?
Actions permits multiple jobs and workflow runs to execute concurrently by default. If simultaneous runs could duplicate deployments, agent commits, or other side effects, use a concurrency group to restrict overlapping work. By default, a group has only one pending run: a newly pending run cancels the previous pending run. Configure queuing if every pending run must execute in order; otherwise, cancellation may discard work you intended to retain.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
