To share an Amazon API cache across more than one process, worker, dyno or machine, put it in Redis instead of a local file or an in-memory Map: every caller reads and writes the same key, and a short SETNX lock makes sure that when several workers miss the same key within the same second, only one of them pays the credit - the rest wait a few hundred milliseconds and read its answer from the cache, for free.
Key Takeaways
- A per-process cache (SQLite, an in-memory Map) does not help a fleet of workers; Redis is the one store every worker already reaches.
- Build the key from the endpoint and the sorted parameters, exactly like a single-process cache - the only change is where the key lives.
SET key value NX EX seconds(SETNX with an expiry) is one atomic Redis command: it is both the lock and its own timeout, so a crashed worker can never hold it forever.- A cache stampede is N workers missing the same key within the same instant; without a lock, N workers each pay a credit for the identical answer.
- Keep billed 404s for about a day, same as any cache; never store 429, 5xx, 401 or 403 - those describe the moment, not the product.
Why does a single-process cache fail across workers?
A SQLite file on one machine, or a Node.js in-memory Map, only has reach inside the process that created it. Run several worker processes behind the same app, or run the same cron on three machines, and each one builds its own cache from scratch: the same ASIN gets looked up, and billed, once per worker instead of once total. Redis fixes this because every worker opens the same connection to the same server, so a key written by worker 1 is read as a hit by workers 2, 3 and 4 a moment later.
A local Redis for development (the production one is wherever your other shared state already lives)
redis-server --daemonize yes
python3 -m venv .venv
.venv/bin/pip install redis requests
What is a cache stampede, and why does a plain Redis GET/SET not stop it?
A stampede happens the instant a hot key expires, or is looked up for the first time, while several workers are asking for it at once: every one of them runs GET key, sees nothing, and proceeds to call the real API - all before the first one has written its answer back. A plain GET then SET has a gap between the two calls with no lock in it, so the number of credits spent for one logical lookup equals the number of workers that missed at the same moment, not one.

cache.py: a Redis cache with a stampede lock
This wraps get() and ApiError from the Python quickstart, unchanged, exactly like the SQLite cache does - only the storage layer and the stampede lock are new. r.set(..., nx=True, ex=...) is redis-py's name for Redis's SET key value NX EX seconds: it sets the key only if it is absent, with its own expiry, as one atomic round trip, so there is no window where the lock exists without a timeout.
cache.py - Redis cache, TTL per endpoint, SETNX stampede lock
import json
import time
import redis
from sellermagnet import ApiError, get
TTL = { # seconds; starting points, tune per use case
"amazon-product-offers": 10 * 60,
"amazon-product-lookup": 12 * 3600,
"amazon-bestsellers": 3600,
"amazon-product-statistics": 24 * 3600,
"amazon-asin-converter": 30 * 86400,
}
DEFAULT_TTL = 3600
NOT_FOUND_TTL = 24 * 3600 # a 404 is billed: remember it
LOCK_TTL = 15 # seconds; longer than one request has any business taking
LOCK_WAIT = 20 # seconds; stay under the client's own 120s request timeout
def cache_key(endpoint: str, **params) -> str:
return "smapi:" + endpoint + ":" + json.dumps(params, sort_keys=True) # never the API key
def cached_get(r: redis.Redis, session, endpoint: str, **params) -> dict:
key = cache_key(endpoint, **params)
raw = r.get(key)
if raw is not None:
cached = json.loads(raw)
if cached.get("not_found"):
raise ApiError(404, "Product not found (cached)")
return cached["data"] # 0 credits
lock_key = key + ":lock"
deadline = time.monotonic() + LOCK_WAIT
while not r.set(lock_key, "1", nx=True, ex=LOCK_TTL):
if time.monotonic() > deadline:
raise TimeoutError(f"cache lock busy too long for {key}")
time.sleep(0.1)
raw = r.get(key) # the lock holder may have finished already
if raw is not None:
cached = json.loads(raw)
if cached.get("not_found"):
raise ApiError(404, "Product not found (cached)")
return cached["data"]
try:
try:
data = get(session, endpoint, **params) # 1 credit
except ApiError as err:
if err.status == 404:
r.set(key, json.dumps({"not_found": True}), ex=NOT_FOUND_TTL) # billed: remember it
raise # 429 / 500 / 502 / 503 are never cached
r.set(key, json.dumps({"data": data}), ex=TTL.get(endpoint, DEFAULT_TTL))
return data
finally:
r.delete(lock_key)
Why poll instead of Redis pub/sub or BLPOP?
A 100ms poll loop adds at most 100ms of latency to the 6 or 7 workers that lose the race, which is nothing next to a scrape that can take up to 120 seconds. Pub/sub or a blocking list needs its own message after every fetch and its own handling for a subscriber that connects after the message already fired; the poll loop has neither failure mode and reads the same key you were already checking.
| Status | Meaning | Billed | Cache it? |
|---|---|---|---|
200 | A fresh or repeat answer | Yes | cache it under TTL[endpoint] |
404 | Not found | Yes | cache it for 24h; never retry |
400 | Missing param (free) or a billed bad value | Mixed | fix the request, never cache |
429 | Per-key concurrency cap, 20s wait then Retry-After | No | never cache; retry after Retry-After |
500 | Internal error, no Retry-After | No (refunded) | never cache; retry once |
502 | Upstream error | Yes | never cache; retry, capped |
503 | Marketplace circuit breaker, Retry-After | Yes | never cache; retry, capped |
Calling it from several workers
Open one redis.Redis per worker (the client is thread-safe and pools its own connections) and pass it into cached_get alongside the usual requests.Session from new_session(). Nothing else about calling the API changes - cached_get(r, session, "amazon-product-lookup", asin="B0CL61F39H", marketplaceId="ATVPDKIKX0DER") returns the same data dict get() would, whichever worker asked first.
main.py - one Redis connection per worker, shared across workers via the server
import redis
from cache import cached_get
from sellermagnet import new_session
r = redis.Redis(host="localhost", port=6379, db=0)
session = new_session()
product = cached_get(r, session, "amazon-product-lookup",
asin="B0CL61F39H", marketplaceId="ATVPDKIKX0DER")
print(product["productInfo"]["title"])
A crashed worker still releases the lock on its own
ex=LOCK_TTL means the lock expires 15 seconds after it was set, win or crash. The finally: r.delete(lock_key) releases it early on a normal return; if the worker is killed mid-fetch, Redis drops the key on its own at the 15-second mark instead of leaving every other caller stuck behind a lock nobody will ever release.
Tested: 8 concurrent workers, 1 credit
cache.py was tested against a real local Redis server (not a mock of the Redis client) and the unmodified sellermagnet.py/retry.py helpers from the Python quickstart, with a fails-closed fake requests.Session.get. 10/10 scenarios pass: a cache hit costs no request; the TTL written per endpoint; an unknown endpoint falls back to the default TTL; a billed 404 is cached and not retried; 429/500/502 responses are never written to the cache; the lock is released even when the fetch raises; a caller that waits for the lock reads the winner's answer without ever calling the API itself; and the stampede test below, 8 real Python threads missing the same key inside the same 0.3-second fetch, with the real API call count asserted at exactly 1.
test_cache.py - the stampede assertion (8 real threads, 1 real API call)
def test_concurrent_requests_for_the_same_key_bill_only_once(self):
"""Cache-stampede guard: 8 threads miss the same key at once; only 1 API call happens."""
call_count = {"n": 0}
lock = threading.Lock()
def slow_fake_get(self_, url, params=None, timeout=None):
with lock:
call_count["n"] += 1
time.sleep(0.3) # simulate the real scrape taking a moment
return FakeResp(200, {"success": True, "data": {"v": 42}}, {})
results = []
errors = []
def worker():
try:
with mock.patch("requests.Session.get", slow_fake_get):
results.append(cached_get(self.r, new_session(), "amazon-product-lookup", asin="B0STAMP"))
except Exception as exc: # pragma: no cover - diagnostic only
errors.append(exc)
threads = [threading.Thread(target=worker) for _ in range(8)]
for t in threads:
t.start()
for t in threads:
t.join(timeout=10)
self.assertEqual(errors, [])
self.assertEqual(len(results), 8)
self.assertTrue(all(r == {"v": 42} for r in results))
self.assertEqual(call_count["n"], 1) # only ONE of the 8 callers paid the credit

Frequently Asked Questions
Does a Redis cache replace the SQLite or in-memory cache from the other caching guide?
Only if you run more than one process. A single script or a single-dyno cron is fine with SQLite or an in-memory Map; Redis earns its keep once two or more workers, web dynos or machines call the API and need to see the same cached answers.
What exactly stops the cache stampede?
A single atomic command, SET key value NX EX seconds (SETNX plus an expiry). Only the first caller to run it gets a true back and goes on to call the real API; every later caller gets false, so it waits and re-reads the cache instead of calling the API itself.
What happens if the worker holding the lock crashes before it finishes?
Nothing has to happen: the lock's own EX expiry (15 seconds in this guide) releases it automatically. No other worker has to detect the crash or clean anything up.
Should the lock TTL match the cache TTL?
No - the lock TTL only needs to outlast one real API call (up to 120 seconds for a slow scrape, 15 is a safer floor for most endpoints); the cache TTL is how long the answer itself stays good, from minutes for offers to days for a barcode mapping.
Can the same approach share a cache across more than one server?
Yes - that is Redis's whole advantage over an in-memory Map: any process that can reach the Redis host, on the same machine or a different one, reads and writes the same keys.
Bottom line: once more than one worker calls the SellerMagnet API, a per-process cache stops protecting your credits the moment two of them miss at once. Redis's SET ... NX EX ... gives every worker the same cache and, with a short lock around the miss path, turns N simultaneous misses back into exactly one paid request. Try it on the 150 credits a free account gets after e-mail verification.