Skip to content

feat(hydrogen): return 429, not 500, when the Storefront API rate limits a request - #4282

Merged
fredericoo merged 12 commits into
mainfrom
feat/storefront-rate-limit-loader
Nov 12, 2026
Merged

fredericoo merged 12 commits into
mainfrom
feat/storefront-rate-limit-loader

Conversation

@benni-rogge

@benni-rogge benni-rogge commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

TL;DR: Let Hydrogen apps return HTTP 429, not 500, 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 StorefrontApiError with status: 429. React Router treats that error as a 500 and 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 429 becomes a page 500. Cart mutations reject or return 500 after a customer-session refresh. Predictive search returns 400.

After

export const loader = withStorefrontRateLimit(async ({ context }: Route.LoaderArgs) => {
  const { data } = await context.get(storefrontClientContext).graphql(QUERY);
  return data;
});

// Root middleware, after next():
requestContext.applyResponseHeaders(response.headers, response.status);

Server handlers use separate explicit options:

const cartHandlers = createCartServerHandlers({ rateLimitHandling: "response" });
const predictiveSearchHandlers = createPredictiveSearchServerHandlers({
  rateLimitHandling: "response",
});

const result = handleShopifyRoutes({
  request, requestContext, storefrontClient,
  handlers: [cartHandlers, predictiveSearchHandlers],
  rateLimitHandling: "response",
});

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

  • Adds raw StorefrontApiError.retryAfter metadata, including its toJSON() output.
  • Adds withStorefrontRateLimit, which maps only typed Storefront API HTTP 429 errors. It throws a response with a fixed body, no-store, and validated retry advice. It never retries or forwards the upstream diagnostic body.
  • Adds an optional response-status argument to applyResponseHeaders. This restores safe rate-limit headers after React Router drops thrown-response headers.
  • Uses an explicit conservative policy when one request sees multiple rate limits. Restored advice uses the latest retry deadline, independent of completion order. Recovered calls can make the delay longer, never shorter. The response's own valid Retry-After and the captured deadline are compared, and the later one wins. If a rate limit happened and the caller omits status, applyResponseHeaders logs one warning.
  • Passes response status through both normal and cloned registered-route finalization paths. A handler that catches an upstream rate limit and returns its own 429 also gets safe headers.
  • With opt-in, cart mutations return 429 with existing code cart_mutation_failed. Predictive search returns 429 with existing code invalid_predictive_search_request. Their finite error-code unions do not expand.
  • With router opt-in, thrown registered-handler rate limits return JSON with generic code rate_limited. That result already uses ShopifyRouteError.code: string.
  • Keeps committed session cookies on mapped cart mutation failures. Native cart forms get plain-text 429 pages; JSON submissions get JSON.
  • Adds optional format: "text" to route error results. Existing results stay JSON.
  • Logs mapped errors once through Hydrogen's logger. Predictive search also logs failed Storefront queries and replaces upstream diagnostic messages with a constant.
  • Updates the React Router template to adopt the loader wrapper, header finalization, and all three server-handler opt-ins.

Developer impact

Includes three minor changesets. The wrapper, metadata, and optional settings are additive. CartErrorCode stays invalid_cart_request | missing_cart | cart_mutation_failed; existing exhaustive switches and Record mappings 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 createShopifyRequestContext capture retry advice automatically.

Apps must adopt the options to change server-handler rate-limit handling. Unwrapped loaders still produce 500. Direct cartHandlers.get() calls still throw. A route handler that throws synchronously now rejects the returned promise, as the handleShopifyRoutes TSDoc already documents.

React Router does not report thrown responses through handleError. Apps adopting the wrapper or handler mapping should forward Hydrogen logs with configureLogging({ 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 429 when enabled.

Out of scope

  • Automatic adoption by existing apps.
  • GraphQL THROTTLED results carried in HTTP 200 responses.
  • Customer Account API rate limits.
  • Deferred failures after the response has started streaming.
  • Changes to platform rate limits or production infrastructure.

Risk

  • The wrapper needs status-aware finalization on the same request context as its Storefront client. Missing either loses restored retry headers.
  • Conservative aggregation can delay retries after a recovered request. This is intentional when the framework loses the selected error's headers.
  • Enabling response mapping changes the error-reporting path from the app boundary to Hydrogen's logger.
  • Predictive search error logs can increase during upstream failures.

How to Test

  1. Run pnpm install && pnpm build:pkgs from the repository root.
  2. In the mock.shop client configuration in templates/react-router/app/lib/storefront.ts, temporarily add:
    fetch: async (input, init) => String(init?.body).includes("query Home")
      ? new Response("private upstream diagnostic", { status: 429, headers: { "Retry-After": "30" } })
      : fetch(input, init),
  3. Run pnpm dev:rr. Open the local URL printed by Vite.
  4. Confirm the page shows "Too many requests". Confirm HTTP 429, Retry-After: 30, and Cache-Control: no-store.
  5. Navigate from /collections to home. Confirm the .data response also has 429 and retry advice.
  6. Change the matcher to "mutation Cart". Submit a native cart form and confirm a plain-text 429 without a redirect.
  7. Submit a JSON cart mutation. Confirm JSON code cart_mutation_failed, status 429, and retry advice.
  8. Change the matcher to "query PredictiveSearch". Open /api/predictive-search?q=shirt. Confirm code invalid_predictive_search_request and status 429.
  9. Remove rateLimitHandling from each factory in turn. Confirm its previous rate-limit behavior returns. Restore both options.
  10. Register a custom handler that throws a StorefrontApiError with status: 429. Confirm router opt-in returns a JSON 429; removing the router option restores propagation to the app error boundary.
  11. Confirm no mapped response includes private upstream diagnostic. Revert the temporary fetch and test handler.

Validation

Local checks passed in the existing Linux Podman builder:

  • Hydrogen: 154 test files, 2,674 tests; type tests report no errors.
  • React Router template: 51 Node integration tests, including real React Router page and .data retry restoration after recovered failures.
  • Repository format and lint checks.
  • Hydrogen TypeScript, Hydrogen build, MiniOxygen build, template typecheck/GraphQL checks, and template production build.
  • Regression coverage includes legacy exhaustive code mappings, opt-in/default paths, refreshed session cookies, synchronous handler throws, conservative retry deadlines, and mutable/cloned response finalization.

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 d2f68d8 predate this opt-in revision and are not current-head downstream rate-limit runtime proof.

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.
@shopify

shopify Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Oxygen deployed a preview of your feat/storefront-rate-limit-loader branch. Details:

Storefront Status Preview link Deployment details Last update (UTC)
Skeleton (skeleton.hydrogen.shop) ✅ Successful (Logs) Preview deployment Inspect deployment November 12, 2026 5:02 PM

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.
@benni-rogge benni-rogge changed the title feat(hydrogen): return 429, not 500, for rate-limited Storefront loaders feat(hydrogen): return 429, not 500, when the Storefront API rate limits a request Oct 29, 2026
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.
@benni-rogge
benni-rogge marked this pull request as ready for review October 30, 2026 00:59
@benni-rogge
benni-rogge requested a review from a team as a code owner October 30, 2026 00:59

@NabeelAhsen NabeelAhsen left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The main 429 mapping looks sound. Two header-handling cases need correction, plus a release-compatibility question below.

@andguy95 andguy95 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread templates/react-router/app/root.tsx Resolved
Comment thread templates/react-router/README.md Resolved
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.
@benni-rogge
benni-rogge requested a review from andguy95 November 5, 2026 05:20

@fredericoo fredericoo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

benni-rogge and others added 2 commits November 5, 2026 13:34
…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
@fredericoo

Copy link
Copy Markdown
Contributor

merged main in to clear the conflicts (628ce0f), mostly imports plus the i18n refactor in request-context.ts - kept your rate-limit bits and main's resolveRequestLocale, dropped normalizeI18n since main replaced it. regenerated the docs json too. typecheck, tests, lint and format pass locally, worth a quick look before you merge

@benni-rogge

Copy link
Copy Markdown
Contributor Author

merged main in to clear the conflicts (628ce0f), mostly imports plus the i18n refactor in request-context.ts - kept your rate-limit bits and main's resolveRequestLocale, dropped normalizeI18n since main replaced it. regenerated the docs json too. typecheck, tests, lint and format pass locally, worth a quick look before you merge

@fredericoo thank you for doing that. LGTM

@fredericoo fredericoo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
@fredericoo

Copy link
Copy Markdown
Contributor

merged main again (78d3965) - this time it was the UCP Link header landing in applyResponseHeaders. kept both: the 429 handling runs, then the UCP link is applied. the hydrogen-request-handlers skill now mentions both the status argument and the Link header. docs json regenerated, all green locally

…limit-loader

# Conflicts:
#	packages/hydrogen/src/core/predictive-search/server-handlers.ts
@fredericoo

Copy link
Copy Markdown
Contributor

one more main merge (dfb5226), just an import clash in the predictive search handlers. CI's green, should be good to merge now

@fredericoo
fredericoo added this pull request to the merge queue Nov 12, 2026
Merged via the queue into main with commit 752bf4d Nov 12, 2026
12 checks passed
@fredericoo
fredericoo deleted the feat/storefront-rate-limit-loader branch November 12, 2026 17:47
andguy95 added a commit that referenced this pull request Nov 13, 2026
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.
andguy95 added a commit that referenced this pull request Nov 18, 2026
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants