diff --git a/.changeset/cool-cache-bro.md b/.changeset/cool-cache-bro.md
index f86dc39339..f342f39e55 100644
--- a/.changeset/cool-cache-bro.md
+++ b/.changeset/cool-cache-bro.md
@@ -28,7 +28,7 @@ import { CacheManager } from '@backstage/backend-common';
 const cacheManager = CacheManager.fromConfig(config);
 const somePluginCache = cacheManager.forPlugin('somePlugin');
 const defaultTtl = 3600;
-const cacheClient = somePluginCache.getClient(defaultTtl);
+const cacheClient = somePluginCache.getClient({ defaultTtl });
 
 // Using the cache client:
 const cachedValue = await cacheClient.get('someKey');
@@ -41,4 +41,19 @@ if (cachedValue) {
 await cacheClient.delete('someKey');
 ```
 
+For simplicity of use, cache clients will swallow client errors by default. Plugin developers may optionally pass an `onError` argument to the `CacheManager.getClient()` method if they wish to capture and handle those errors in a custom way.
+
+```typescript
+const cacheClient = somePluginCache.getClient({
+  defaultTtl: 3600,
+  onError: 'reject',
+});
+
+try {
+  await cacheClient.delete('someKey');
+} catch (e) {
+  // Attempt again, log, alert, etc.
+}
+```
+
 Configuring a cache store is optional. Even when no cache store is configured, the cache manager will dutifully pass plugins a manager that resolves a cache client that does not actually write or read any data.
diff --git a/packages/backend-common/api-report.md b/packages/backend-common/api-report.md
index 339a291ff3..bd1b017574 100644
--- a/packages/backend-common/api-report.md
+++ b/packages/backend-common/api-report.md
@@ -66,8 +66,8 @@ export class BitbucketUrlReader implements UrlReader {
 // @public
 export interface CacheClient {
     delete(key: string): Promise<void>;
-    get(key: string): Promise<JsonValue>;
-    set(key: string, value: JsonValue, ttl?: number): Promise<void>;
+    get(key: string): Promise<JsonValue | undefined>;
+    set(key: string, value: JsonValue, options: CacheSetOptions): Promise<void>;
 }
 
 // @public
@@ -254,7 +254,7 @@ export function notFoundHandler(): RequestHandler;
 
 // @public
 export type PluginCacheManager = {
-    getClient: (ttl: number) => CacheClient;
+    getClient: (options: ClientOptions) => CacheClient;
 };
 
 // @public