fix: handle Figma 429 rate limits with visible backoff and a clear error

claude · claude · commit 6f308946b12d · 2026-07-08T14:28:40.000Z
Previously a rate-limited request retried silently -- the sync modal sat on 'Finding exportable assets…' with no feedback while the code slept, and exhausted retries surfaced as a generic API error. During downloads, every queued item would have retried and failed independently. - figmaFetch now honors Retry-After (capped at 120s), surfaces a per-second countdown in the progress modal via a provider status channel, and throws a typed SyncRateLimitError with a clear 'wait a minute and sync again' message when retries are exhausted. - The engine aborts the download queue on the first rate-limited item (the rest would only hit the same limit) and fails the sync with the rate-limit message. Nothing is lost: lastRemoteVersion is not advanced, and a later re-sync skips already-imported items by hash. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Kv5GTb2ddUqL46zSitS6Lf
diff --git a/packages/root-cms/ui/components/AssetBrowser/AssetSyncModals.tsx b/packages/root-cms/ui/components/AssetBrowser/AssetSyncModals.tsx
@@ -346,17 +346,26 @@ export function SyncProgressModal(props: {
           <div className="AssetBrowser__syncProgress__running">
             <Loader color="gray" size="sm" />
             <div className="AssetBrowser__syncProgress__phase">
-              {progress.phase === 'enumerating' && 'Finding exportable assets…'}
-              {progress.phase === 'downloading' &&
-                (progress.total
-                  ? `Importing ${Math.min(
-                      (progress.completed ?? 0) + 1,
-                      progress.total
-                    )} of ${progress.total}${
-                      progress.currentName ? ` — ${progress.currentName}` : ''
-                    }`
-                  : 'Importing…')}
-              {progress.phase === 'finalizing' && 'Finishing up…'}
+              {progress.note ? (
+                progress.note
+              ) : (
+                <>
+                  {progress.phase === 'enumerating' &&
+                    'Finding exportable assets…'}
+                  {progress.phase === 'downloading' &&
+                    (progress.total
+                      ? `Importing ${Math.min(
+                          (progress.completed ?? 0) + 1,
+                          progress.total
+                        )} of ${progress.total}${
+                          progress.currentName
+                            ? ` — ${progress.currentName}`
+                            : ''
+                        }`
+                      : 'Importing…')}
+                  {progress.phase === 'finalizing' && 'Finishing up…'}
+                </>
+              )}
             </div>
           </div>
         )}
diff --git a/packages/root-cms/ui/utils/asset-sync/engine.test.ts b/packages/root-cms/ui/utils/asset-sync/engine.test.ts
@@ -11,6 +11,7 @@ import {
   RemoteAsset,
   SyncAuthContext,
   SyncInProgressError,
+  SyncRateLimitError,
 } from './types.js';
 
 /** Builds a fake Timestamp-ish value. */
@@ -395,6 +396,33 @@ describe('syncFolder', () => {
     );
   });
 
+  it('aborts the download queue on a rate limit and rethrows', async () => {
+    const folder = makeFolder();
+    const {provider} = makeProvider({
+      version: 'v1',
+      remote: [
+        {remoteId: 'file:1:0', filename: 'a.png', contents: 'aaa'},
+        {remoteId: 'file:2:0', filename: 'b.png', contents: 'bbb'},
+      ],
+    });
+    provider.download = async () => {
+      throw new SyncRateLimitError('rate limited');
+    };
+    const deps = makeDeps({folder});
+    await expect(
+      syncFolder({folder, provider, auth: AUTH, deps, concurrency: 1})
+    ).rejects.toThrow(SyncRateLimitError);
+    // The first rate-limited item aborts the queue -- the remaining items
+    // are not attempted (each would just be rate-limited again), and no
+    // partial writes happen for them.
+    expect(deps.createAssetFile).not.toHaveBeenCalled();
+    expect(deps.finalizeFolderSync).toHaveBeenCalledWith(
+      'folder-icons',
+      expect.objectContaining({ok: false, error: 'rate limited'}),
+      {remoteVersion: undefined}
+    );
+  });
+
   it('refuses to run while another sync holds a fresh lease', async () => {
     const folder = makeFolder({
       state: {status: 'syncing', startedAt: ts(), startedBy: 'b@example.com'},
diff --git a/packages/root-cms/ui/utils/asset-sync/engine.ts b/packages/root-cms/ui/utils/asset-sync/engine.ts
@@ -54,6 +54,8 @@ import {
   SyncAuthContext,
   SyncInProgressError,
   SyncProgress,
+  SyncProviderContext,
+  SyncRateLimitError,
   SyncSummary,
 } from './types.js';
 
@@ -153,9 +155,22 @@ export async function syncFolder(
     throw new Error(`Unknown sync provider: ${sync.provider}`);
   }
   const auth = options.auth ?? createBrowserAuthContext(provider.id);
-  const onProgress = options.onProgress || (() => {});
   const concurrency = options.concurrency || DEFAULT_CONCURRENCY;
 
+  // Progress reporting. Providers report transient status (e.g. rate-limit
+  // backoff countdowns) through `providerCtx.onStatus`, which re-emits the
+  // latest progress with a `note`; regular progress events clear the note.
+  let lastProgress: SyncProgress = {phase: 'enumerating'};
+  const onProgress = (progress: SyncProgress) => {
+    lastProgress = progress;
+    options.onProgress?.(progress);
+  };
+  const providerCtx: SyncProviderContext = {
+    onStatus: (message: string) => {
+      options.onProgress?.({...lastProgress, note: message});
+    },
+  };
+
   // Resolve the token before taking the lease or writing anything, so a
   // missing token surfaces as a prompt with zero side effects.
   await auth.getToken();
@@ -189,7 +204,7 @@ export async function syncFolder(
 
   try {
     onProgress({phase: 'enumerating'});
-    const remoteList = await provider.listRemoteAssets(sync, auth);
+    const remoteList = await provider.listRemoteAssets(sync, auth, providerCtx);
     remoteVersion = remoteList.version;
 
     const folderPath = joinFolderPath(folder.parent, folder.name);
@@ -252,7 +267,7 @@ export async function syncFolder(
     // Let the provider batch per-item download prep (e.g. Figma render URL
     // resolution) for just the items that actually need downloading.
     if (provider.prepareDownloads && candidates.length > 0) {
-      await provider.prepareDownloads(candidates, sync, auth);
+      await provider.prepareDownloads(candidates, sync, auth, providerCtx);
     }
 
     // Pre-assign de-duped names for new imports (deterministic by remote id
@@ -275,7 +290,16 @@ export async function syncFolder(
     let completed = 0;
     onProgress({phase: 'downloading', total: candidates.length, completed});
 
+    // A rate-limited item means every remaining item would also be
+    // rate-limited (after its own long retries), so the first one aborts
+    // the queue. Nothing is lost: re-syncing later resumes cheaply since
+    // already-imported items are skipped by content hash.
+    let rateLimitError: SyncRateLimitError | null = null;
+
     await runPool(candidates, concurrency, async (remoteAsset) => {
+      if (rateLimitError) {
+        return;
+      }
       onProgress({
         phase: 'downloading',
         total: candidates.length,
@@ -285,6 +309,10 @@ export async function syncFolder(
       try {
         await syncItem(remoteAsset);
       } catch (err: any) {
+        if (err instanceof SyncRateLimitError) {
+          rateLimitError = err;
+          return;
+        }
         console.error(`failed to sync "${remoteAsset.name}":`, err);
         summary.failed.push({
           name: remoteAsset.name,
@@ -295,9 +323,18 @@ export async function syncFolder(
       onProgress({phase: 'downloading', total: candidates.length, completed});
     });
 
+    if (rateLimitError) {
+      throw rateLimitError;
+    }
+
     async function syncItem(remoteAsset: RemoteAsset) {
       const existing = syncedByRemoteId.get(remoteAsset.remoteId);
-      const file = await provider!.download(remoteAsset, sync!, auth);
+      const file = await provider!.download(
+        remoteAsset,
+        sync!,
+        auth,
+        providerCtx
+      );
       const contentHash = await deps.sha1(file);
       // Unchanged bytes: strict no-op (no upload, no db write, no fan-out).
       if (existing && existing.source?.contentHash === contentHash) {
diff --git a/packages/root-cms/ui/utils/asset-sync/figma.test.ts b/packages/root-cms/ui/utils/asset-sync/figma.test.ts
@@ -1,5 +1,6 @@
 import {afterEach, describe, expect, it, vi} from 'vitest';
 import {FIGMA_PROVIDER, buildExportFilename, parseFigmaUrl} from './figma.js';
+import {SyncAuthContext, SyncRateLimitError} from './types.js';
 
 describe('parseFigmaUrl', () => {
   it('parses design URLs', () => {
@@ -157,6 +158,84 @@ describe('FIGMA_PROVIDER.validateToken', () => {
   });
 });
 
+describe('FIGMA_PROVIDER rate limiting', () => {
+  const SOURCE = {
+    provider: 'figma',
+    url: 'https://www.figma.com/design/AbC123/File',
+    figma: {fileKey: 'AbC123'},
+  };
+  const AUTH: SyncAuthContext = {
+    getToken: async () => 'tok',
+    invalidateToken: () => {},
+  };
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it('retries a rate-limited request and reports a countdown', async () => {
+    vi.useFakeTimers();
+    let calls = 0;
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        calls += 1;
+        if (calls === 1) {
+          return {
+            ok: false,
+            status: 429,
+            headers: {get: () => '1'},
+            json: async () => ({}),
+          } as any;
+        }
+        return {
+          ok: true,
+          status: 200,
+          headers: {get: () => null},
+          json: async () => ({
+            version: '9',
+            document: {id: '0:0', name: 'root', children: []},
+          }),
+        } as any;
+      })
+    );
+    const notes: string[] = [];
+    const promise = FIGMA_PROVIDER.listRemoteAssets(SOURCE, AUTH, {
+      onStatus: (message) => notes.push(message),
+    });
+    await vi.advanceTimersByTimeAsync(11_000);
+    const result = await promise;
+    expect(result.version).toEqual('9');
+    expect(calls).toEqual(2);
+    expect(notes.some((n) => n.includes('rate limit'))).toBe(true);
+  });
+
+  it('throws SyncRateLimitError after exhausting retries', async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        async () =>
+          ({
+            ok: false,
+            status: 429,
+            headers: {get: () => null},
+            json: async () => ({}),
+          }) as any
+      )
+    );
+    const promise = FIGMA_PROVIDER.listRemoteAssets(SOURCE, AUTH).catch(
+      (err) => err
+    );
+    // Backoff floors are 10s + 20s + 30s before the final attempt.
+    await vi.advanceTimersByTimeAsync(61_000);
+    const err = await promise;
+    expect(err).toBeInstanceOf(SyncRateLimitError);
+    expect(String(err.message)).toContain('rate-limiting');
+  });
+});
+
 describe('FIGMA_PROVIDER.parseSourceUrl', () => {
   it('returns a source ref for figma URLs', () => {
     const url = 'https://www.figma.com/design/AbC123xyz/File?node-id=1-2';
diff --git a/packages/root-cms/ui/utils/asset-sync/figma.ts b/packages/root-cms/ui/utils/asset-sync/figma.ts
@@ -17,6 +17,8 @@ import {
   RemoteAssetList,
   SyncAccessError,
   SyncAuthContext,
+  SyncProviderContext,
+  SyncRateLimitError,
   SyncSourceRef,
   SyncTokenRequiredError,
 } from './types.js';
@@ -34,6 +36,9 @@ const IMAGES_BATCH_SIZE = 50;
 /** Max retries for rate-limited (429) API requests. */
 const MAX_RATE_LIMIT_RETRIES = 3;
 
+/** Max seconds to wait out a single Retry-After before retrying. */
+const MAX_RETRY_WAIT_SECONDS = 120;
+
 /** Formats supported by the Figma images API. */
 type FigmaExportFormat = 'png' | 'jpg' | 'svg' | 'pdf';
 
@@ -116,19 +121,43 @@ export function parseFigmaUrl(url: string): FigmaSourceRef | null {
 
 /**
  * Calls the Figma REST API, mapping auth failures to typed errors and
- * retrying rate-limited requests with backoff.
+ * retrying rate-limited requests with backoff. Rate-limit waits honor the
+ * `Retry-After` header and are surfaced to the user as a countdown via
+ * `onStatus`; when retries are exhausted a {@link SyncRateLimitError} is
+ * thrown so the sync fails with a clear "try again in a bit" message
+ * instead of hanging silently.
  */
-async function figmaFetch(path: string, token: string): Promise<any> {
+async function figmaFetch(
+  path: string,
+  token: string,
+  onStatus?: (message: string) => void
+): Promise<any> {
   let attempt = 0;
   for (;;) {
     const res = await fetch(`${FIGMA_API_ORIGIN}${path}`, {
       headers: {'X-Figma-Token': token},
     });
-    if (res.status === 429 && attempt < MAX_RATE_LIMIT_RETRIES) {
+    if (res.status === 429) {
       attempt += 1;
-      const retryAfter = Number(res.headers.get('retry-after')) || 0;
-      const delaySeconds = Math.min(Math.max(retryAfter, 5 * attempt), 60);
-      await sleep(delaySeconds * 1000);
+      const retryAfter = Number(res.headers?.get?.('retry-after')) || 0;
+      if (attempt > MAX_RATE_LIMIT_RETRIES) {
+        throw new SyncRateLimitError(
+          'Figma is rate-limiting API requests for your account. Wait a minute or two, then sync again — the sync picks up where it left off.',
+          retryAfter || undefined
+        );
+      }
+      // Honor Retry-After (capped), with a growing floor when absent.
+      const delaySeconds = Math.min(
+        Math.max(retryAfter, 10 * attempt),
+        MAX_RETRY_WAIT_SECONDS
+      );
+      for (let remaining = delaySeconds; remaining > 0; remaining--) {
+        onStatus?.(
+          `Figma rate limit reached — retrying in ${remaining}s… (attempt ${attempt} of ${MAX_RATE_LIMIT_RETRIES})`
+        );
+        await sleep(1000);
+      }
+      onStatus?.('Retrying…');
       continue;
     }
     if (res.ok) {
@@ -241,7 +270,8 @@ function collectExportableNodes(
 
 async function listRemoteAssets(
   source: SyncSourceRef,
-  auth: SyncAuthContext
+  auth: SyncAuthContext,
+  ctx?: SyncProviderContext
 ): Promise<RemoteAssetList> {
   const figma = source.figma;
   if (!figma?.fileKey) {
@@ -254,7 +284,8 @@ async function listRemoteAssets(
   if (figma.nodeId) {
     const data = await figmaFetch(
       `/v1/files/${encodeURIComponent(figma.fileKey)}/nodes?ids=${encodeURIComponent(figma.nodeId)}`,
-      token
+      token,
+      ctx?.onStatus
     );
     version = data?.version ? String(data.version) : undefined;
     const nodeData = data?.nodes?.[figma.nodeId];
@@ -267,7 +298,8 @@ async function listRemoteAssets(
   } else {
     const data = await figmaFetch(
       `/v1/files/${encodeURIComponent(figma.fileKey)}`,
-      token
+      token,
+      ctx?.onStatus
     );
     version = data?.version ? String(data.version) : undefined;
     roots = data?.document ? [data.document] : [];
@@ -301,7 +333,8 @@ async function listRemoteAssets(
 async function prepareDownloads(
   assets: RemoteAsset[],
   source: SyncSourceRef,
-  auth: SyncAuthContext
+  auth: SyncAuthContext,
+  ctx?: SyncProviderContext
 ): Promise<void> {
   const fileKey = source.figma?.fileKey;
   if (!fileKey) {
@@ -334,7 +367,8 @@ async function prepareDownloads(
       }
       const data = await figmaFetch(
         `/v1/images/${encodeURIComponent(fileKey)}?${params.toString()}`,
-        token
+        token,
+        ctx?.onStatus
       );
       if (data?.err) {
         throw new Error(`Figma image render failed: ${data.err}`);
diff --git a/packages/root-cms/ui/utils/asset-sync/types.ts b/packages/root-cms/ui/utils/asset-sync/types.ts
