From dd1bb93c725dd3d0d61e236f709e0cadd3fe3bfa Mon Sep 17 00:00:00 2001
From: Ryan Ghadimi <ghadimir@github.com>
Date: Fri, 16 Jan 2026 10:00:15 +0000
Subject: [PATCH] New error type for cache RL

---
 packages/cache/RELEASES.md                          |  2 +-
 .../cache/src/internal/shared/cacheTwirpClient.ts   | 13 ++++++-------
 packages/cache/src/internal/shared/errors.ts        |  7 +++++++
 3 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/packages/cache/RELEASES.md b/packages/cache/RELEASES.md
index 8ae33f8a..821c80aa 100644
--- a/packages/cache/RELEASES.md
+++ b/packages/cache/RELEASES.md
@@ -2,7 +2,7 @@
 
 ### 5.0.3
 
-Fail cache saves on rate limit errors from the cache service to prevent slowing down impacted runs [2243](https://github.com/actions/toolkit/pull/2243).
+Fail cache operations on rate limit errors from the cache service to prevent slowing down impacted runs [2243](https://github.com/actions/toolkit/pull/2243).
 
 ### 5.0.1
 
diff --git a/packages/cache/src/internal/shared/cacheTwirpClient.ts b/packages/cache/src/internal/shared/cacheTwirpClient.ts
index 72bd6c0a..c1e14240 100644
--- a/packages/cache/src/internal/shared/cacheTwirpClient.ts
+++ b/packages/cache/src/internal/shared/cacheTwirpClient.ts
@@ -1,6 +1,6 @@
 import {info, debug, warning} from '@actions/core'
 import {getUserAgentString} from './user-agent'
-import {NetworkError, UsageError} from './errors'
+import {NetworkError, RateLimitError, UsageError} from './errors'
 import {getCacheServiceURL} from '../config'
 import {getRuntimeToken} from '../cacheUtils'
 import {BearerCredentialHandler} from '@actions/http-client/lib/auth'
@@ -121,7 +121,7 @@ class CacheServiceClient implements Rpc {
               )
             }
           }
-          throw new Error(`Rate limited: ${errorMessage}`)
+          throw new RateLimitError(`Rate limited: ${errorMessage}`)
         }
       } catch (error) {
         if (error instanceof SyntaxError) {
@@ -132,13 +132,12 @@ class CacheServiceClient implements Rpc {
           throw error
         }
 
-        if (NetworkError.isNetworkErrorCode(error?.code)) {
-          throw new NetworkError(error?.code)
+        if (error instanceof RateLimitError) {
+          throw error
         }
 
-        // Re-throw rate limit errors without retry
-        if (error.message?.startsWith('Rate limited:')) {
-          throw error
+        if (NetworkError.isNetworkErrorCode(error?.code)) {
+          throw new NetworkError(error?.code)
         }
 
         isRetryable = true
diff --git a/packages/cache/src/internal/shared/errors.ts b/packages/cache/src/internal/shared/errors.ts
index 9ec29f6b..5e90a299 100644
--- a/packages/cache/src/internal/shared/errors.ts
+++ b/packages/cache/src/internal/shared/errors.ts
@@ -70,3 +70,10 @@ export class UsageError extends Error {
     return msg.includes('insufficient usage')
   }
 }
+
+export class RateLimitError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'RateLimitError'
+  }
+}