Rate limits cause a hard failure instead of retry

[zanieb]

Description:

This action fails when a GitHub API rate limit is encountered, e.g., https://github.com/astral-sh/uv/actions/runs/18688106891/job/53286544594

Run actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
Installed versions
  GraalPy version 24.1 was not found in the local cache
  Error: API rate limit exceeded for installation. If you reach out to GitHub Support for help, please include the request ID 5841:12068:2A62DF:B7984D:68F7A08C and timestamp 2025-10-21 15:02:36 UTC. For more on scraping GitHub and how it may affect your rights, please review our Terms of Service (https://docs.github.com/en/site-policy/github-terms/github-terms-of-service)

GitHub's rate limits have recently been reduced, and we're seeing far more failures from this.

While I'd generally expect setup-python to avoid hitting a rate-limited API, I'd also expect it to retry on spurious HTTP errors and handle rate limiting, especially for a first-party API.

Action version:

5.6.0

Platform:

• Ubuntu
• macOS
• Windows

Runner type:

• Hosted
• Self-hosted

Tools version:

Repro steps:

See description. Requires hitting a GitHub rate limit.

Expected behavior:

I expect the action to retry in a backoff, respecting the retry-after header.

Actual behavior:

The action hard fails.

[priya-kinthali]

Hello @zanieb👋,
Thank you for reporting this issue. We will investigate it and get back to you as soon as we have some feedback.

[aparnajyothi-y]

Hello @zanieb, thank you for creating this issue. In this case the workflow is starting in a fully rate-limited state, so the very first GitHub API request made by setup-python receives a 403 with zero remaining quota. When the rate limit is already exhausted, retries cannot succeed because each request is immediately rejected. This behavior is consistent with GitHub’s documented secondary-rate-limit and abuse-protection rules as documented here.
Today, setup-python does not implement rate-limit–aware backoff (for example, reading X-RateLimit-Reset and sleeping until the next window). It relies on the underlying Octokit/HTTP client’s generic retry behavior, which does not help when the initial request itself begins under a hard limit. This aligns with current REST client behavior described here.
.

Supporting this scenario would require explicit handling for rate-limited startup conditions — detecting the 403, reading the reset timestamp, and waiting or deferring subsequent calls. We are evaluating what it would take to add this safely and consistently across all platforms, while staying aligned with GitHub’s recommended rate-limit handling strategies.

[aparnajyothi-y]

Hi @zanieb, just checking back in to see if you had a chance to review the explanation above or if you had any follow-up questions or additional context to share.

Happy to clarify further or discuss next steps if helpful. Thanks!

[zanieb]

Hey!

Yeah I think the request here is to "implement rate-limit–aware backoff" by sleeping if the reset time is within a reasonable window. I'm not asking for immediate retry.

[aparnajyothi-y]

Hello @zanieb, Thanks for clarifying, that helps. Implementing a rate-limit–aware backoff (sleeping until reset when it’s within a reasonable window, rather than immediately retrying) makes sense, but it would be a behavioral change beyond the current scope of this issue.

This is better tracked as a feature request, so we can evaluate it alongside similar enhancements and consider the broader impact and default behavior. We’ll update this accordingly and revisit it in that context.
Please feel free to reach us in case of further concerns/clarifications needed :)