Repository navigation
feat(hydrogen): return 429, not 500, when the Storefront API rate limits a request - #4282
Conversation
Add withStorefrontRateLimit and storefrontRateLimitHeaders. The wrapper maps a StorefrontApiError with status 429 to a thrown 429 Response with a fixed body, Cache-Control: no-store, and a validated Retry-After value. Other errors pass through unchanged. The wrapper logs the original error once through Hydrogen's logger, because React Router doesn't pass thrown responses to handleError. StorefrontApiError now exposes the raw retry-after header as retryAfter. The React Router template wraps each Storefront page loader and exports the headers function from the root route and from each wrapped route.
|
Oxygen deployed a preview of your
Learn more about Hydrogen's GitHub integration. |
… rate limits handleShopifyRoutes now answers a thrown StorefrontApiError with status 429 with a 429 JSON error result: code "rate_limited", a constant message, Cache-Control: no-store, and a validated Retry-After header. This covers custom createShopifyRouteHandler handlers and the cart GET route. Every other thrown error still rejects. The cart POST handler maps a rate-limited mutation to the same 429 result and keeps the committed customer session headers. CartErrorCode gains "rate_limited". The predictive search route returns 429 "rate_limited" on a rate limit. Its other Storefront API failures stay 400, but the message no longer includes part of the upstream body. A direct cartHandlers.get() call still throws the StorefrontApiError, so a loader keeps using withStorefrontRateLimit. The route handlers and withStorefrontRateLimit share one internal Retry-After validator. Each path logs the original error once, at error level.
React Router drops the headers of a thrown response. The previous commits asked apps to export `storefrontRateLimitHeaders` as `headers` from the root route and from each wrapped route. That step is easy to miss. Move the step into the root middleware call that apps already make: - The Storefront API client records a 429 and its Retry-After value on the request context. - `applyResponseHeaders(headers, status?)` accepts the response status. For a 429 after a recorded rate limit, it sets `Cache-Control: no-store`, removes `Surrogate-Control` and vendor `*-Cache-Control` headers, and adds the validated Retry-After value when the response has none. Other statuses keep their cache headers. - The template passes `response.status` and drops the six `headers` exports. `storefrontRateLimitHeaders` is removed. It was not released. The template tests now run React Router with middleware enabled. They cover page and `.data` responses for root and child loaders, and show that a call without the status loses Retry-After.
Address four review suggestions for the Storefront API 429 handling: - The predictive search route returns its failures as results, so no outer boundary logged them. Log the original error once at `error` level with scope `predictive-search-api`, for a 429 and for other failed queries. Invalid search settings are not logged. Caller bodies stay constant. - A rate-limited native cart form submission got a raw JSON page. Send the constant message as a plain-text 429 with the same Retry-After and `no-store` headers. A redirect would hide the 429. Route error results accept `format: "text"` for this. JSON requests don't change. - A custom route handler that throws before it returns a promise skipped the 429 mapping and its log. Call handlers through an async function, so a synchronous 429 is mapped and other synchronous throws reject the returned promise. An unmatched route still returns `null`. - Show the loader adoption as one checklist: the wrapper, the status argument, and the request context of the client that the loaders use. Update the remaining one-argument snippets in the storefront client and migration skills, and in the package README.
NabeelAhsen
left a comment
There was a problem hiding this comment.
The main 429 mapping looks sound. Two header-handling cases need correction, plus a release-compatibility question below.
andguy95
left a comment
There was a problem hiding this comment.
Core 429 mapping and header safety look good 🙏 Ran the Hydrogen suites for the touched files (394 pass) and the template integration tests (50 pass) locally, and probed a few option combinations. Nabeel's three threads look properly addressed.
One blocking test fix, the rest are non-blocking - mostly about how the three opt-ins interact.
Warn when applyResponseHeaders lacks a status after a rate limit, emit the later Retry-After deadline on every path, skip logging aborted predictive searches, always run route handlers through a promise, and document the option interplay.
fredericoo
left a comment
There was a problem hiding this comment.
on top of what @andguy95 found, some docs!
looks good, and will work fine for every framework that supports request/response
nextjs will still fall back to error.tsx which is a 500, but thats beyond our capabilities (their RSC transport works this way)
…limit-loader # Conflicts: # packages/hydrogen/docs/generated/generated_docs_data_v2.json # packages/hydrogen/src/client/client.ts # packages/hydrogen/src/core/request-context.test.ts # packages/hydrogen/src/core/request-context.ts # packages/hydrogen/src/core/request-routing/registered-routes.ts # templates/react-router/app/root.tsx
|
merged main in to clear the conflicts (628ce0f), mostly imports plus the i18n refactor in |
@fredericoo thank you for doing that. LGTM |
fredericoo
left a comment
There was a problem hiding this comment.
LGTM, thanks for sorting the stale caveats
…limit-loader # Conflicts: # packages/hydrogen/docs/generated/generated_docs_data_v2.json # packages/hydrogen/skills/hydrogen-request-handlers/SKILL.md # packages/hydrogen/src/core/request-context.test.ts # packages/hydrogen/src/core/request-context.ts
|
merged main again (78d3965) - this time it was the UCP |
…limit-loader # Conflicts: # packages/hydrogen/src/core/predictive-search/server-handlers.ts
|
one more main merge (dfb5226), just an import clash in the predictive search handlers. CI's green, should be good to merge now |
The cart GET marks its response personalized before it fetches, and applyResponseHeaders applies the private value after the 429 no-store, as it already does for Customer Account requests. The #4282 test asserted plain no-store for a rate-limited GET, so it now asserts the private value, and the applyResponseHeaders docs say a marked response keeps it.
The cart GET marks its response personalized before it fetches, and applyResponseHeaders applies the private value after the 429 no-store, as it already does for Customer Account requests. The #4282 test asserted plain no-store for a rate-limited GET, so it now asserts the private value, and the applyResponseHeaders docs say a marked response keeps it.
TL;DR: Let Hydrogen apps return HTTP
429, not500, when the Storefront API rate limits a request. Page loaders and server-handler mapping are explicit opt-ins. Existing handler error-code unions stay unchanged.The Storefront client already throws a typed
StorefrontApiErrorwithstatus: 429. React Router treats that error as a500and drops the retry advice. Mapping at the HTTP boundary preserves the client error contract and lets the app choose its response policy.Before
An uncaught Storefront API
429becomes a page500. Cart mutations reject or return500after a customer-session refresh. Predictive search returns400.After
Server handlers use separate explicit options:
Each option controls its own API. The factory options map handled cart mutations and predictive search failures. The router option maps thrown errors from registered handlers, including cart reads and custom handlers. Without these options, previous rate-limit handling remains.
What this changes
StorefrontApiError.retryAftermetadata, including itstoJSON()output.withStorefrontRateLimit, which maps only typed Storefront API HTTP429errors. It throws a response with a fixed body,no-store, and validated retry advice. It never retries or forwards the upstream diagnostic body.applyResponseHeaders. This restores safe rate-limit headers after React Router drops thrown-response headers.Retry-Afterand the captured deadline are compared, and the later one wins. If a rate limit happened and the caller omitsstatus,applyResponseHeaderslogs one warning.429also gets safe headers.429with existing codecart_mutation_failed. Predictive search returns429with existing codeinvalid_predictive_search_request. Their finite error-code unions do not expand.rate_limited. That result already usesShopifyRouteError.code: string.429pages; JSON submissions get JSON.format: "text"to route error results. Existing results stay JSON.Developer impact
Includes three minor changesets. The wrapper, metadata, and optional settings are additive.
CartErrorCodestaysinvalid_cart_request | missing_cart | cart_mutation_failed; existing exhaustive switches andRecordmappings remain valid. Predictive search's inferred error-code type also stays unchanged.The request-context capture hook is optional, so hand-written contexts do not need a new required method. Contexts from
createShopifyRequestContextcapture retry advice automatically.Apps must adopt the options to change server-handler rate-limit handling. Unwrapped loaders still produce
500. DirectcartHandlers.get()calls still throw. A route handler that throws synchronously now rejects the returned promise, as thehandleShopifyRoutesTSDoc already documents.React Router does not report thrown responses through
handleError. Apps adopting the wrapper or handler mapping should forward Hydrogen logs withconfigureLogging({ logger }).UX impact
The updated template shows "Too many requests" for rate-limited pages. Native cart forms show a constant plain-text retry message. Cart and search clients continue to receive failure responses, now with
429when enabled.Out of scope
THROTTLEDresults carried in HTTP200responses.Risk
How to Test
pnpm install && pnpm build:pkgsfrom the repository root.templates/react-router/app/lib/storefront.ts, temporarily add:pnpm dev:rr. Open the local URL printed by Vite.429,Retry-After: 30, andCache-Control: no-store./collectionsto home. Confirm the.dataresponse also has429and retry advice."mutation Cart". Submit a native cart form and confirm a plain-text429without a redirect.cart_mutation_failed, status429, and retry advice."query PredictiveSearch". Open/api/predictive-search?q=shirt. Confirm codeinvalid_predictive_search_requestand status429.rateLimitHandlingfrom each factory in turn. Confirm its previous rate-limit behavior returns. Restore both options.StorefrontApiErrorwithstatus: 429. Confirm router opt-in returns a JSON429; removing the router option restores propagation to the app error boundary.private upstream diagnostic. Revert the temporary fetch and test handler.Validation
Local checks passed in the existing Linux Podman builder:
.dataretry restoration after recovered failures.Builder:
us-docker.pkg.dev/shopify-ci/docker-hub-remote/golang@sha256:972b4110ba0f47539a975c31e52c64765e1ff19f2d74469ae4a595c6676e80a5. Source mounted read-only; check execution used no network. Exact check script:~/swarms/hydrogen-429-10291001/out/test-runs/minor-checks-1104.sh.Review feedback is addressed at
e43c13c; CI for this head is pending. Human approval remains required.The first attempts failed because some GitHub-hosted runner egress IPs are not allowed by Shopify's policy. A 40-job controlled probe reproduced IP-dependent outcomes with the same actor/token/endpoint: 38 runners passed and two eastus3 runners received the exact allowlist rejection. Both denied IPs are absent from Shopify's pinned runner-IP catalog. The live organization list remains owner-gated. Refreshing its Terraform-managed runner CIDRs is a separate infrastructure follow-up; no allowlist or token policy was changed for this PR.
All three Nabeel threads were answered and resolved. Local containers exited; the isolated check directory was removed. Shared Node and package-cache volumes were retained.
Earlier Edge and MiniOxygen tests at
d2f68d8predate this opt-in revision and are not current-head downstream rate-limit runtime proof.