Cloudflare KV API Error Codes: 10028 Means Two Things

My stats endpoint has been throwing since August 11, and while I was probing the Cloudflare Workers KV REST API to find out how much of my key inventory I could read in one shot, I kept getting HTTP 400 with "code": 10028. So I looked up 10028 in Cloudflare's documentation, found a page for it, and read this: The add list items operation contains duplicate items.

I was not adding list items. I was listing keys with limit=1. The documented meaning of 10028 belongs to Cloudflare Lists and Bulk Redirects, a product I do not use, and Workers KV had borrowed the number for something else entirely.

That sent me on a detour. Over about forty minutes on 2026-08-16 I fired 24 probes at the read and list surface of the KV REST API against my own production namespace and wrote down every code that came back. Five of the six codes KV returned have no documentation page at all. The sixth has one, and it is wrong for KV. Below is the table that does not exist upstream.

What the docs actually cover

Cloudflare's 10xxx error index lists 18 codes. Every one of them describes Lists or Bulk Redirects: duplicate list items, redirect source URLs that are too long, invalid redirect status codes. Workers KV is not mentioned on the page. Neither is any other storage product.

Meanwhile the KV REST API returns codes from that same numeric space. I checked which of the codes I collected have a support page, by requesting .../cloudflare-10xxx-errors/error-<code>/ for each:

error-10000  404
error-10009  404
error-10013  404
error-10028  200   <- exists, describes Bulk Redirects
error-10029  404
error-10030  404

R2, the sibling storage product, publishes a proper error code table. KV has no equivalent page. If you search the literal message strings KV returns, you get nothing useful either. I tried limit argument must be at least 10 and You must request a minimum of 1 key and found no discussion of either. I am stating that as an absence in my own searching, not as a measurement of how often people hit these.

The codes are overloaded, so the message is the only signal

The important structural fact is that a single code covers unrelated failures. 10028 came back for both a floor violation and a ceiling violation on the same parameter. 10029 came back for three different problems across two different endpoints. If you write error handling that branches on errors[0].code, you cannot tell those cases apart. You have to parse the human-readable string, which is the thing every API style guide tells you not to depend on.

Listing keys: an undocumented minimum of 10

The list keys documentation says exactly one thing about the bound: limit is the maximum number of keys returned. The default is 1,000 keys, which is the maximum. A maximum, and nothing about a floor. There is a floor, and it is 10.

limit	HTTP	code	message
0	400	10028	limit argument must be at least 10
1	400	10028	limit argument must be at least 10
9	400	10028	limit argument must be at least 10
10	200		10 keys
11	200		11 keys
1000	200		999 keys
1001	400	10028	limit argument must be no greater than 1000
-5	400	10028	limit argument must be at least 10
abc	400	10028	limit argument must be at least 10
omitted	200		999 keys
cursor=garbage	400	10029	Invalid cursor

Two details in that table are worth pulling out. limit=abc produces the floor error rather than a type error, so a non-numeric value is being coerced to zero somewhere and then compared against 10. If you build a query string from a variable that is occasionally undefined, the API will tell you your number is too small when your problem is that you did not send a number.

And limit=1000 returned 999 keys, deterministically, on five consecutive runs, with the cursor still set. That is the short-page behaviour I measured back in August 11, where asking for 1,000 got me 957 and the page length turned out to carry no information in either direction. It has not gone away; it has just settled at a different number. Do not terminate a pagination loop on keys.length < limit. Terminate on the cursor.

Bulk get: the ceiling is documented, the floor is not

The bulk get reference says Array of keys to retrieve (maximum of 100). That maximum is real and it is enforced. There is also a minimum of 1, which is not written anywhere, and there are no error codes on the page at all.

request body	HTTP	code	message
0 keys	400	10029	You must request a minimum of 1 key
1 key	200		1 value
100 keys	200		100 values
101 keys	400	10029	You can request a maximum of 100 keys
{}	400	10029	You must request a minimum of 1 key
{"keys":"abc"}	400	10029	You must request a minimum of 1 key
["dup","dup","dup"]	200		duplicates accepted

The row I find most annoying is {"keys":"abc"}. A string where an array belongs is a type error, and the API reports it as a count error. You will go looking for the place that built an empty array when the actual bug is the place that forgot to wrap a value in one.

The last row is the joke that made me write this post. Sending the same key three times returns 200 and KV does not care. Duplicate entries in a request are precisely what the documented meaning of 10028 describes, and the endpoint that borrows 10028 accepts duplicates without comment.

The rest of the surface

Four more codes came out of the remaining probes:

probe	HTTP	code	message
GET a key that does not exist	404	10009	get: key not found
GET metadata for a missing key	404	10009	metadata: key not found
key name of 513 bytes	414	10030	UTF-8 encoded length of 513 exceeds key length limit of 512.
namespace id of all zeroes	404	10013	get namespace: namespace not found
invalid bearer token	401	10000	Authentication error
no Authorization header	401	10000	Authentication error

10030 is the only one that comes back as HTTP 414, URI Too Long, which makes sense once you notice the key name travels in the path rather than the body. If you are catching on status code, a 414 in a storage client will look like a malformed URL rather than a value that is 1 byte over a limit.

10000 is the same code Wrangler surfaces when your credentials are wrong, which I worked through separately. It is the one code in this set that behaves like a normal, single-meaning error.

What I changed

My reader now branches on the message substring rather than the code, with a comment pointing at this table so the next person does not assume the code is enough:

def kv_error(resp):
    e = (resp.json().get("errors") or [{}])[0]
    code, msg = e.get("code"), e.get("message", "")
    # 10028/10029 are overloaded; the code alone cannot tell these apart.
    if "must be at least" in msg or "minimum of" in msg:
        return "below_floor"
    if "no greater than" in msg or "maximum of" in msg:
        return "above_ceiling"
    if "Invalid cursor" in msg:
        return "bad_cursor"
    return f"unhandled:{code}:{msg}"

Fragile, and I would rather not. The alternative is treating every 400 from KV as unretryable and logging the message, which is what I do in the paths where I do not need to distinguish. Both are worse than a documented code, and neither is available. Note that none of these are latency failures, which look completely different and which I timed separately; a 400 here arrives immediately.

The reason I was in here at all is that reading 1,782 keys one at a time is what kills my stats endpoint with error 1101. Bulk get at 100 keys per call turns 1,782 operations into 18. Finding that out cost me a detour through an error code that Cloudflare documents as belonging to Bulk Redirects, and I would have skipped the detour if a table like the one above existed. When I did the same exercise for Supabase Storage error codes the failure mode was different: those were documented but the HTTP statuses were wrong. Here the statuses are right and the codes are unlabelled.

Caveats

These probes ran against one namespace on one account on one day, on the read and list surface only. I did not probe writes, deletes, or bulk write, so nothing here should be read as the full KV error catalogue. Codes could plausibly differ by plan or region, and I have no way to check that from a single account. I also did not determine why limit=1000 yields 999; my earlier post established that page length is uninformative in both directions, and I have not gotten further than that.

If you have hit a KV code that is not in this table, I would like to add it. The gap between what the API returns and what is written down is wide enough that I doubt six codes is all of it.

If you want the probe script and the rest of the ops tooling I run this business on, it is in the Playbook.

Every code, message, and HTTP status above came from 24 live requests I made to the Cloudflare KV REST API on 2026-08-16 against my own PICKLOG_STATS namespace, pasted from the responses rather than retyped. The four documentation quotes are linked inline and were fetched the same day, as were the six HTTP status checks on the error-<code> support pages. I looked for community discussion of these specific message strings and found none, which I have described as an absence in my searching rather than evidence about anyone else's experience. Cloudflare's community forum has returned 403 to my requests since August 5, so it is not represented here.