“Cache service responded with 429” means the Actions cache refused a request because the repository is over its rate. GitHub allows 200 cache uploads, 1,500 downloads and 400 deletes a minute per repository, and fails further requests until the limit resets, with the time left in a Retry-After header. It is a rate limit and not a full cache. A matrix whose legs all save at once is the likeliest way to reach it.
- A 429 from the cache is a rate limit: 200 uploads, 1,500 downloads and 400 deletes a minute per repository.
- GitHub fails further requests until the limit resets, and the time left is in the Retry-After header.
- The cache client logs the failure and carries on, so the job runs without its cache instead of failing.
- A matrix that saves from every leg at once is the likeliest cause; save from one job and restore in the rest.
- Spread legs with max-parallel, save fewer entries per job and do not retry in a loop.
This post covers what the message is, which of the three limits a job hit, why the job carries on instead of failing, how to count your own saves and the changes that keep a workflow under the rate. The limits and the header are from GitHub’s documentation, and the behaviour of the cache client is from its source, both read on 15 November 2026.
What does “Cache service responded with 429” mean?
The words are written by @actions/cache, the library behind actions/cache and the cache inputs of the setup actions. On one of its two paths to the cache service, when the service answers a request with a status that is not a success, the client throws an error whose text is “Cache service responded with” and the status. So the number is the service’s own, and 429 is the standard HTTP code for “too many requests in a given amount of time”, which the standard says may carry a Retry-After header telling the client how long to wait.
The client’s other path, the one for the newer cache service, words the same failure differently, and a log from it will not contain the phrase in this post’s title. A request that is refused with 429 there fails as “Failed request: (429)” under a “Rate limited:” prefix, and if the response carries a positive Retry-After the client first prints the warning “You’ve hit a rate limit, your rate limit will reset in N seconds”. On a restore the whole is logged as “Failed to restore:” followed by that text. On a save, the first request is the reservation of the entry, and the client reports a failed reservation as “Failed to save: Unable to reserve cache with key” and the key, “another job may be creating this cache”, as an information line. So a rate limit on an upload can read like two jobs racing for a key. Search the log for “429” and for “rate limit”, and not only for the title’s words.
Which of the three limits did the job hit?
| Operation | Limit | Past the limit |
|---|---|---|
| Uploads of cache entries | 200 a minute per repository | New uploads are rejected until the limit resets |
| Downloads of cache entries | 1,500 a minute per repository | Downloads fail until the limit resets |
| Deletes of cache entries, by key or by ID | 400 a minute per repository | Deletes fail until the limit resets |
The step that failed tells you which. A restore is a download, and the limit that applies is 1,500 a minute. A save is an upload, and the limit is 200. A step in a script that calls the cache API to delete entries, including a loop that clears old keys, is the third. GitHub announced the upload limit on 16 January 2026, in response to repositories that uploaded a high volume of entries in very short periods, and said it does not affect entries that jobs download. The limits post has every other Actions limit in one table.
The arithmetic of a matrix makes the upload limit easy to reach. A matrix is limited to 256 jobs, and if every leg saves one entry when it finishes, a full matrix that finishes together asks for more than the 200 uploads a minute that the repository is allowed. Fewer legs can do it too, if each saves several entries and they finish in the same minute.
Does a 429 fail the job?
No. In the client’s source, a failure to restore is caught, logged and the build continues: the comment on that code says “warn on cache restore failure and continue build”, and a failure to save is caught the same way. The only error annotation in that code is for an HTTP client error with a status of 500 or more; a 429, and every other failure, is a warning, or on a failed reservation an information line. A failed restore is then a cache miss, so the job installs what it would have restored, and a failed save means the next run finds no entry. The cost of a 429 is therefore minutes, not a red run: the job that missed its cache runs slower, and is billed for the extra minutes.
The client does not retry a rate-limited request. Version 5.0.3 of @actions/cache added “Prevent retries for rate limited cache operations”, and the code that does it is in the client for the newer service, so a 429 there is final for that attempt and the wait is yours to arrange. A workflow that wraps the cache step in its own retry loop will just meet the limit again, and spend more of the minute’s allowance doing so.
How do I find which runs and steps hit it?
Search the logs for the status and the wording. The GitHub CLI prints a run’s full log with gh run view --log, and a filter turns that into a count for each run.
# every line that carries the status or the wording, with its step
gh run view <run-id> --log | grep -n -i -E "429|rate limit"
# how many runs in the last fifty hit it
for id in $(gh run list --limit 50 --json databaseId -q '.[].databaseId'); do
n=$(gh run view "$id" --log 2>/dev/null | grep -c -i -E "429|rate limit")
echo "$id $n"
done
Then compare the count with the shape of the workflow. If the 429s are on a few runs and all inside one minute, the workflow has a spike: a matrix, or several workflows triggered by the same push. If they are spread through the day, something in the repository is writing entries all the time, such as a job that saves a new key on every commit. The cache limit post explains why that pattern also fills the 10 GB.
How do I keep a workflow under the rate?
Change the workflow so that fewer requests are made in the same minute. In order of how much they remove:
Save from one job and restore in the rest. If every leg of a matrix saves the same dependencies, one job on the default branch can own the save and the legs restore only. GitHub’s actions/cache/restore and actions/cache/save actions exist for this split, and it replaces an upload from every leg with one upload.
jobs:
warm:
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- run: npm ci
- uses: actions/cache/save@v6
with:
path: ~/.npm
key: npm-${{ hashFiles('package-lock.json') }}
test:
needs: warm
if: ${{ !cancelled() }}
runs-on: ubuntu-latest
strategy:
max-parallel: 4
matrix:
shard: [1, 2, 3, 4, 5, 6, 7, 8]
steps:
- uses: actions/checkout@v7
- uses: actions/cache/restore@v6
with:
path: ~/.npm
key: npm-${{ hashFiles('package-lock.json') }}
- run: npm ci
- run: npm test -- --shard=${{ matrix.shard }}/8
Spread the legs of a matrix. By default GitHub runs as many jobs of a matrix in parallel as the runners allow, and max-parallel sets a ceiling on that, 4 in the sample. A leg that runs for a minute or more cannot finish more often than the ceiling allows, so a ceiling of 4 asks for at most 4 saves a minute from the matrix, far inside 200. A lower ceiling costs wall-clock time, so choose the highest that keeps the arithmetic inside the limit.
Save fewer entries per job. One entry per tool is cheaper than one per directory. A setup action that already caches the package manager does not also need a hand-written step for the same directory, and the second entry is two more requests for nothing. Delete less too: a cleanup loop that removes keys one by one spends the 400 deletes a minute, and GitHub’s documentation counts a delete by key and by ID against the same limit.
Honour the header. If a script of your own talks to the cache API, read Retry-After and wait that long before the next request, instead of trying again at once. That is the one number GitHub gives for when the limit resets.
Is a 503 the same problem?
No. A 503 is the service failing to answer, not your repository exceeding a rate, and nothing in a workflow changes it. The client treats it as it treats a 429 and carries on with a cache miss, so the job continues. If 503s are frequent, check GitHub’s status page before changing the workflow, and treat the cost as the same one as a 429: the minutes a job spends doing what the cache would have saved.
How does this differ on runners.io?
A job on our runners reaches our cache, which is included and not metered, without a change to the workflow, unless an owner or admin has switched it off or, on a Windows job, its setup could not be completed; the limits above are GitHub’s, and apply to GitHub’s cache. The Actions cache documentation says how a job reaches ours and how an owner can turn it off, in which case the job’s cache requests go to GitHub, and its limits, again. If the minutes lost to misses are the cost you care about, the post on our cache shows what a job can read and write, the pricing page has the rate for a minute, and the guide to keeping a build cache between runs covers the build output a cache of this kind does not hold.
Sources
- Dependency caching reference (docs.github.com)
- Actions limits (docs.github.com)
- Rate limiting for actions cache entries (GitHub changelog, 16 January 2026) (github.blog)
- cacheHttpClient.ts (actions/toolkit, @actions/cache) (github.com)
- cache.ts (actions/toolkit, @actions/cache) (github.com)
- config.ts (actions/toolkit, @actions/cache) (github.com)
- cacheTwirpClient.ts (actions/toolkit, @actions/cache) (github.com)
- @actions/cache releases (actions/toolkit) (github.com)
- RFC 6585, section 4: 429 Too Many Requests (IETF) (rfc-editor.org)
- Workflow syntax for GitHub Actions (docs.github.com)
- actions/cache (github.com)
- gh run view (GitHub CLI manual) (cli.github.com)
Frequently asked questions
What does "Cache service responded with 429" mean in GitHub Actions?
The cache service refused a request because the repository sent too many in a minute. GitHub allows 200 uploads, 1,500 downloads and 400 deletes a minute per repository and fails further requests until the limit resets.
Does a 429 from the Actions cache fail my job?
No. In the cache client's source a failed restore or save is caught and logged, as a warning, and the build continues. The job runs without its cache and takes the extra minutes.
How long until the cache rate limit resets?
GitHub returns the time until the limit resets in the Retry-After header of the response. On the newer cache service path the client prints it as a warning before the failure: you have hit a rate limit, and it will reset in a number of seconds.
How do I avoid cache 429 errors in a matrix?
Let one job save and have the matrix legs only restore, using actions/cache/save and actions/cache/restore. Cap how many legs run at once with max-parallel, and save fewer entries per job.