lychee "429 Too Many Requests" rate limit checking links in CI

By Daniel Zoghalchali·Latchkey

A host returned HTTP 429 because lychee sent too many requests too quickly. The links are valid; the checker was throttled. Without retries or exclusions, lychee counts 429 as an error and fails the job.

What this error means

lychee reports "[429] Too Many Requests" for many URLs on the same domain (often github.com, crates.io, or docs sites), inflating the error count.

[docs/api.md]:
  [429] https://github.com/org/repo/issues/1 | Too Many Requests
  [429] https://github.com/org/repo/issues/2 | Too Many Requests

Errors: 2

Common causes

High request concurrency hits a rate limit

lychee checks links in parallel; a burst of requests to one host triggers 429 responses.

Unauthenticated GitHub link checks

GitHub throttles anonymous requests hard, so checking many github.com links without a token yields 429s.

How to fix it

Throttle, retry, and pass a token

1. Lower concurrency and enable retries with a wait.
2. Provide a GitHub token so github.com links are not anonymous.
3. Optionally set accept to allow 429 as non-fatal.

- uses: lycheeverse/lychee-action@v2
  with:
    args: --max-concurrency 4 --retry-wait-time 10 --accept 200,429 './**/*.md'
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Exclude hosts that always rate-limit checkers

If a host cannot be checked reliably, exclude it rather than letting 429s fail the build.

# lychee.toml
exclude = ["^https://www\\.reddit\\.com"]

How to prevent it

• Set a GITHUB_TOKEN so github.com link checks are authenticated.
• Lower --max-concurrency and enable retries for rate-limited hosts.
• Accept 429 as non-fatal, or exclude hosts that throttle checkers.

Frequently asked questions

Related guides

References

• GitHub Actions documentation