fix: retry read-only API requests the site rate-limits

[dcalhoun]

What?

Retry api-fetch requests with 429 status codes.

Why?

The editor sends numerous requests on load. Some hosts deny these requests with 429 responses. This disrupts the editor load. In particular, blocks like Categories List will stop functioning as Gutenberg's store will cache the response as an empty collection, which prevents the block from fetching the actual data later.

How?

Wrap @wordpress/api-fetch's default handler with retry logic. The logic targets safely repeatable requests with a backoff timing and jitter. It favors a Retry-After header value if present.

Note: this does not address these failures for the development server. The request in that environment are CORS and occur for preload OPTIONS requests. The status code is hidden from JavaScript in that context, so we cannot accurately detect the request should be retried.

Testing Instructions

Tip

This was primarily reproduced via WoW (Atomic) sites where the CDN often limits the batch of requests when the editor loads.

1. Load the editor with a bundle (with GUTENBERG_EDITOR_URL unset)
2. Inspect the editor after launch with Chrome's inspector (if needed, reload the editor page)
3. Note any [GBK] Retrying... logs in the console for failed requests
4. Insert the Categories List block
5. Verify the block lists the sites categories, it is not empty/collapsed

Accessibility Testing Instructions

N/A, no presentation changes.

Screenshots or screencast

N/A, no presentation changes.

---

AI-generated details

What: Retries GET, HEAD, and OPTIONS requests that receive a 429, up to twice. It waits for Retry-After when present, but fails at once if it asks for more than 10s, since retries inside that window would also fail. Otherwise it waits 0.5–1s then 2–4s with jitter.

Why: Some hosts, such as WP Cloud sites, throttle the burst of REST requests sent while the editor loads. core-data caches a failed taxonomy entity config for the session, so the Categories List and Terms List blocks then never fetch terms until the editor reloads. #691 exposed this without adding requests: Gutenberg #78568 lazy-loads user pattern categories, which used to load the taxonomy config early, moving that load into the throttled part of the burst.

How: Wraps api-fetch's fetch handler rather than adding a middleware, so each network request is retried once, including fetchAllMiddleware pages. The wrapper requests the raw response to read its status and then parses it as api-fetch does, since api-fetch does not expose its parsing. Other statuses, network errors, offline, and aborted requests behave as before.

Limitation: With the Vite dev server, the editor is cross-origin, so a throttled request fails at the CORS preflight as a network error with no status. This PR does not cover that case.

Testing:

1. Load the editor with a production build on a site that throttles (e.g. a WP Cloud staging site) until taxonomies?context=view returns 429.
2. Confirm the console logs Retrying GET …/taxonomies?context=view… after a 429 response.
3. Insert a Categories List block and confirm it lists the site's categories.

🤖 Generated with Claude Code

https://claude.ai/code/session_011A5docu5NJzK5jRH8X5AnS

[wpmobilebot]

XCFramework Build

This PR's XCFramework is available for testing. Add the following to your Package.swift:

.package(url: "https://github.com/wordpress-mobile/GutenbergKit", branch: "pr-build/741")

_{Built from 275cedd}

[oguzkocer]

I've left a minor suggestion, but otherwise looks good to me.

[oguzkocer]

My understanding is that this will keep waiting for the entire delay duration even if the signal is aborted during that time, and a listener for the abort event could reject early with signal.reason.

[dcalhoun]

Thanks. Addressed in 275cedd.