PlutocracyMercury developer docs

Caching and rate limits

What Mercury caches on its side, what it tells your browser (nothing, today), how fresh results are, and how hard you can call it.

Freshness

Mercury indexes a store's catalogue from Shopify webhooks, so a product change reaches collections, search results and zones within moments of Shopify telling Mercury, not on a schedule. Merchandising changes made in the Mercury admin (sorting, badges, campaigns, synonyms, redirects) apply as soon as they are saved, except where one of the short caches below still holds an older answer.

What Mercury caches

  • Collection, search and zone responses are computed per request from the Redis index. There is no response cache in front of them.
  • Products by handle (/search/product/{handles}) keep a short server-side cache per store and URL.

What your browser is told

Nothing: Mercury sends no Cache-Control or ETag headers, so browsers and CDNs treat responses as uncacheable by default. If you call Mercury from your own server, caching there is up to you. A short time-to-live (30–60 seconds) on collection pages and search results, keyed on the full URL including the currency, is safe for most stores; zones that depend on the cart should not be cached.

All routes allow any origin (Access-Control-Allow-Origin: *), so a browser can call them from any storefront domain. That's also why the Origin header, not CORS, decides which store a request is for.

Rate limits

There is no per-client rate limit in the API today. AWS API Gateway applies its regional account limits in front of everything, which ordinary storefront traffic is far below. Be a good citizen anyway:

  • debounce autocomplete;
  • page with take and skip rather than asking for everything;
  • don't poll; Mercury's data changes when the store's does;
  • back off on 500 and 503, and don't retry 4xx.

Mercury may add limits in a future version. They would arrive with 429 responses and a version note in the changelog.

Region failover

Each region reads its own Redis replica. If a region's Redis can't be reached when the service starts, it connects to another region's, so a regional problem degrades latency rather than availability. A search that hits a dropped connection is retried once.