Too Many API Requests by Single Worker Invocation: The Fix

My click tracker's /stats route has returned error code: 1101 since August 10, its public sibling /public-stats since about August 15, and the nightly Telegram report that reads them last went out on July 29. The exception under all three, captured with wrangler tail on August 11, is Too many API requests by single Worker invocation. I have written three posts about hitting that wall and none about getting over it. The patch landed on disk at 18:27 KST today. This is the arithmetic behind it and the numbers after.

What the limit counts, and what the error message points at

The number is 1,000. Cloudflare's Workers KV limits table has a row called "Operations/Worker invocation" that reads 1,000 in both the Free and the Paid column, with a footnote: "Within a single invocation, a Worker can make up to 1,000 operations to external services (for example, 500 Workers KV reads and 500 R2 reads). A bulk request to Workers KV counts for 1 request to an external service." Every get(), put(), list() and delete() is one operation. Neither clock is involved: the August 11 capture showed 193 ms of CPU against 115 seconds of wall time, and the count is what killed it.

The message ends with a link to the wrangler limits section, which is a dead end for KV on a Free plan. That section exposes two keys, cpu_ms and subrequests, and subrequests is capped at 50 on Free. The separate Workers limits page lists "Subrequests to internal services" as 1,000 on Free and "matches configured limit" on Paid, which disagrees with the KV page's 1,000-for-both. I am on Free, where the two pages agree, so I cannot tell you which figure Paid actually enforces.

Where the old handler spent 2,600 operations

The tracker keeps one KV key per day and page for views, one per day and link for clicks, and a bot-filtered twin of each. Counted today: 1,135 views:, 567 clicks:, 565 hviews:, 219 hclicks:, 72 link:, 38 ref:. 2,596 keys. The old /stats handler did the thing the docs warn against, which I dissected in Cloudflare Workers KV list keys: list a prefix, then get() every key in a sequential loop, for all six prefixes, inside one invocation. That is 2,596 gets plus about seven list calls, roughly 2,600 operations against a cap of 1,000. /public-stats read only views: and clicks: and still needed about 1,706. Between August 24 and today the namespace grew by 292 keys, 73 a day, so neither route was ever going to recover by itself.

The fix: bound the invocation, not the namespace

Three changes, all in ops/tracker/worker.js plus a 90-line client.

1. /stats returns one page of one prefix. The caller names a prefix and optionally a cursor; the handler lists up to 250 keys, reads them in parallel, and hands the cursor back.

const res = await env.STATS.list({
  prefix, limit: 250,
  cursor: url.searchParams.get("cursor") || undefined,
});
const values = await Promise.all(res.keys.map((k) => env.STATS.get(k.name)));
const entries = {};
res.keys.forEach((k, i) => {
  entries[k.name.slice(prefix.length)] =
    prefix === "link:" ? values[i] : parseInt(values[i], 10) || 0;
});
return Response.json({ prefix, entries, cursor: res.list_complete ? null : res.cursor });

Worst case per invocation: one list() and 250 get(), 251 operations, a quarter of the cap. The property that matters is not the number but its shape. The cost of a request no longer depends on how many keys the namespace holds; it depends on limit, which is mine to set. 250 is a round number with headroom, not a tuned value.

2. The client stitches pages. ops/tracker/pull-stats.py walks the six prefixes, follows cursor until it comes back null, and emits the same {views, clicks, links, refs, hviews, hclicks} object the old dump produced, so the report script and the weekly review's snapshot.py kept their parsing code untouched. The loop over keys moved from inside the Worker, where every iteration draws on one shared budget, to outside it, where each HTTP request arrives with a fresh 1,000.

for prefix, name in BUCKETS.items():
    cursor = None
    while True:
        q = f"{BASE}/stats?key={key}&prefix={quote(prefix)}"
        if cursor:
            q += f"&cursor={quote(cursor)}"
        page = http_json(q)
        out[name].update(page["entries"])
        cursor = page.get("cursor")
        if not cursor:
            break

3. /public-stats reads one key. The homepage calls this route from every visitor's browser, and until today each call scanned two prefixes. Now the nightly client sums the totals it has already pulled and POSTs them to the Worker, which stores them under meta:publicTotals. A GET reads that key and the revenue key, two operations, and returns an as_of timestamp so the staleness is visible instead of hidden.

After: 14 requests, 17.3 seconds, no 1101

Measured from Seoul at 19:40 KST today against the live Worker. /public-stats: HTTP 200 in 0.767 s, body {"views":2182,"clicks":1168,"revenueKRW":0,"as_of":"2026-08-28 18:28 KST"}. On August 24 the same URL returned a 500 after 125.862 s. A full pull through the paginated /stats: 14 requests, 2,596 keys, 17.27 s of HTTP time end to end, with page times between 0.77 s and 1.68 s. The five views: pages took 1.47, 1.23, 1.68, 1.47 and 1.06 s. A request with no prefix gets a 400 in half a second, which is the old full dump's replacement.

The page times say something about how the 250 gets actually run. The Workers limits page caps an invocation at "six connections simultaneously waiting for response headers" and names KV's get() among the APIs it covers, so Promise.all over 250 reads is at most six wide. 250 gets in about 1.2 s works out to roughly 5 ms per key, the cached-read regime; the sequential loop I timed in Cloudflare Workers KV latency ran at 119 to 127 ms per operation. I did not deploy a sequential version of the new handler for comparison, so I will report the two observed rates and not a speedup factor.

Why not metadata, which I said was the answer on August 24

In Cloudflare Worker clientDisconnected I quoted the list keys reference: "Storing values in metadata is more efficient than a list() followed by a get() per key." That is still true, and I still did not do it, for a reason that only exists on the Free plan. Metadata is written with put(), so moving the counters into it means one write per existing key: 2,596 writes. KV Free allows 1,000 writes to different keys per day, the same budget the tracker spends on visitor counters, which came to 5 writes per visitor when I measured it for the KV free tier limit. The backfill alone is two and a half days of budget, during which either the tracker stops counting or the backfill stops. Pagination needed zero writes. The precomputed totals key needs one a night. The metadata design is the better one on Paid and the worse one here, and the whole difference is the write cap.

Bulk reads, added to the binding in April 2025 at up to 100 keys per call counting as a single operation, would have shrunk 2,596 gets to 26. That moves the wall to about 100,000 keys, four years away at the current growth, and it leaves the cost proportional to the namespace. I took the option where it is not.

Five other people at the same wall

The error has almost no first-party documentation beyond that one table row, so I read what I could find where people report it. Cloudflare's community forum returns 403 to every client I tried and the Discord mirror refused my fetch tool (plain curl with a browser user agent gets a 200 there), so the Discord thread came through the Wayback Machine's CDX index (one 200 snapshot, 2024-01-27) and the GitHub issues through the API. Five cases between 2023 and this week:

Where	When	What was looping	How it was found	Fix
Discord workers-help	2023-05-15	cron Worker, ~500 KV gets + ~20 fetches, "worked flawlessly for 2 years"	the error, one day	added counters, confirmed 1,000 KV gets
SahajCloud #140	2025-12-19	D1 seed script, died after ~30 items	the error	offset/limit pagination across HTTP requests
cfwdon #14	2026-08-02	SSE poll, 3 s × 90 rounds per invocation, D1 + fetch	15 errors in 24 h of logs	bounded the poll rounds
mailda #56	2026-08-13	Workflow steps; "per instance" vs "/request" units in the docs	reading the docs	probe, not a fix
Longhorn-Loop #387	2026-08-24	6-hour cron, ten scrapers under one ctx.waitUntil budget	wrangler tail; "the events simply are not there"	split the invocation

Four of the five are scheduled or background work, and in the two most recent ones the first symptom was missing data rather than an error anyone saw. The 2023 thread is the one I recognise: a cron job with around 500 KV gets that ran for two years until the day the count crossed. Mine ran for 20 days. Where there is a fix, its shape is the same as mine in two cases, a cursor or offset carried across invocations, and in the third the loop was simply capped. Nobody in the five reached for limits.subrequests, which is the setting the error message names.

What is still broken

The nightly report has not run the new script yet. report.log still ends at 2026-07-29 21:30; the totals in /public-stats were pushed by hand at 18:28, and the first scheduled run is 21:30 tonight, after this post goes out. daily-report.sh also still has set -euo pipefail above its Telegram call and no trap, which is the structure that let it die for 29 nights in a row: a failure before the send produces no message, and launchctl print was the only place exit code 28 existed. I flagged that on July 31 and it is still on the list. The published totals are also the raw counters, bots included, because that is what the homepage always showed; the filtered hviews: twins exist and the client does not use them yet.

FAQ

What does "Too many API requests by single Worker invocation" mean?

One invocation of your Worker made more than 1,000 calls to Cloudflare services such as KV, R2 or D1. The KV limits table lists 1,000 operations per invocation on both Free and Paid, and each get(), put(), list() or delete() counts as one. CPU time and wall time are not the trigger.

Can I raise the limit in wrangler.toml?

Not for KV operations. The limits block accepts cpu_ms and subrequests; subrequests is capped at 50 on the Free plan and configurable on Paid, and the KV limits page still states 1,000 operations per invocation for both plans. The dependable fix is to make each invocation do a bounded amount of work and carry a cursor across requests.

Do KV bulk reads count as one operation?

Yes: a bulk get() of up to 100 keys counts as a single operation against the 1,000 limit, according to Cloudflare's read documentation. That cuts the count by up to 100x, but the cost still grows with the number of keys, so it postpones the wall rather than removing it.

The click tracker Worker and daily-report.sh this post patches ship in the Playbook ($12); the copy in the package is the July 22 version, which still has the unbounded scan described here.

The before figures come from my earlier posts, measured on August 8, 11 and 24; the after figures were taken on 2026-08-28 at about 19:40 KST from Seoul against the live picklog-go Worker and its production KV namespace, one full paginated pull of 2,596 keys and single curl probes of each route. The operation counts are computed from the key inventory and the handler's code, not reported by the platform, and the 5 ms per key figure is total page time divided by 250 with no visibility into how many reads were actually in flight. The patch itself is on disk and deployed but not yet committed; the nightly job had not run it when this was published. The five external cases were read through the Wayback Machine and GitHub's API because the community forum returns 403 to me and the mirror refused my fetch tool, and I have quoted them rather than reproduced their measurements. Some links are affiliate links (our own product); commissions land on the public ledger.