Supabase Storage Error Codes: 20 of 22 Returned HTTP 400

The script that uploads this blog's images calls raise_for_status() and stops there. That was fine until I asked it a harder question: when an upload fails, was the file too big, was the MIME type refused, or did the object already exist? The HTTP status could not tell me, because it was 400 every time. So I spent an afternoon firing deliberately broken requests at my own production bucket to find out where the real answer lives.

23 probes, 20 of them HTTP 400

The bucket under test is the one this site actually serves images from: blog-images, public, storage server 1.69.0, holding the 138 rows of OG thumbnails generated with Python Pillow, with a file_size_limit of 2,097,152 bytes and an allowed_mime_types allowlist of image/webp, image/png, image/svg+xml. Those two constraints are what make the experiment possible — I can trigger EntityTooLarge and InvalidMimeType for real instead of guessing at them.

Twenty-three probes, twenty-two of which are errors. Twenty of those twenty-two came back 400 on the wire. In thirteen of them, the status inside the response body disagreed with the status on the wire.

Probe	Wire	Body statusCode	code
GET missing object	400	404	NoSuchKey
HEAD missing object	400	—	— (0-byte body)
GET object in missing bucket	400	404	NoSuchBucket
Upload with anon key (RLS)	400	403	AccessDenied
Upload with garbage JWT	400	403	AccessDenied
Duplicate upload, no upsert	400	409	KeyAlreadyExists
Upload 3 MiB into a 2 MiB bucket	400	413	EntityTooLarge
Upload text/plain	400	415	InvalidMimeType
Create bucket that already exists	400	409	BucketAlreadyExists
Signed URL with garbage token	400	400	InvalidJWT
Range past end of file	416	—	—
List objects in missing bucket	200	—	— ([])
S3 protocol, no credentials	403	—	AccessDenied (XML)

Every JSON error body carried exactly four keys, eighteen times out of eighteen:

$ curl -s -w "HTTP=%{http_code}\n" \
    "$SUPABASE_URL/storage/v1/object/public/blog-images/nope.webp"
{"statusCode":"404","error":"not_found","message":"Object not found","code":"NoSuchKey"}
HTTP=400

I ran the matrix first in Python and did not believe it, so I re-ran five of the probes with curl. Same answer. This is not a client artifact.

Two of the four keys are worth staring at. statusCode is a string, and it is the only place the real HTTP semantics survive. code is the stable identifier the documentation tells you to branch on. Neither one is the number your HTTP library will hand you.

HEAD destroys the answer completely

The sharpest case is the one with no body at all. A HEAD request for a missing object returns 400, advertises content-type: application/json and content-length: 88, and then sends zero bytes. The real status was only ever in the body, and HEAD has no body, so nothing is recoverable.

Somebody noticed this before me. supabase/storage#323, opened on 2023-05-04, is titled "HEAD /object/authenticated/<bucket>/not_found should use status code 404", and the reporter's argument is exactly the measurement I repeated today: "HEAD request will not have a body and there is no way for client to know what happened." It was closed as not planned. Three years and three months later, on server 1.69.0, the behavior is unchanged.

Why 400, in the server's own type definitions

The mechanism is legible from the source. src/internal/errors/renderable.ts is twenty-nine lines and contains three fields that explain everything:

The interface declares httpStatusCode: number for the intended status, a rendered body type whose statusCode is a string, and userStatusCode?: number for what actually goes on the wire. That last field is optional, and the string userStatusCode appears zero times in the 682-line codes.ts where all the errors are defined. Nothing sets it, so nothing overrides the default.

The documented codes are unreachable from the JS client

If you use storage-js, the practical damage is worse than a wrong number. Its error handler reads:

const status = error.status || 500
const statusCode = err?.statusCode || status + ''
reject(new StorageApiError(_getErrorMessage(err), status, statusCode))

So error.status is the wire status, which is 400 for almost everything, and error.statusCode is the string from the body, which is the useful one. StorageApiError itself carries four properties: name, message, status, statusCode. The code field never makes the trip. The stable identifiers the error-codes page exists to document — NoSuchKey, EntityTooLarge, KeyAlreadyExists — are dropped by the official client before your catch block ever sees them.

The error-handling guide describes the surviving field as "error.statusCode (HTTP status as a string)". On my project it is not the HTTP status. It is the status the server wanted to send, which is a different and considerably more useful thing, and the two are unequal in thirteen of my twenty-two error probes.

The reference table is a subset, and nine rows disagree with the code

Since the wire status is useless and the client drops code, the published error-codes table is what most people will reach for. I parsed the server's enum at the v1.69.0 tag and compared. The tag and master are byte-identical, so this is the version my server reports running.

• The ErrorCode enum has 57 members. The documentation table lists 32. Every documented code exists in the enum, so the table is a clean subset — but 25 codes ship undocumented, including ExpiredToken, TusError, FeatureNotEnabled, DatabaseReadOnly, and a family of Iceberg and S3Vector errors.
• Of the 29 documented codes that have a factory in codes.ts, 20 agree with the table and 9 do not.

Code	Docs say	Server source says
InvalidJWT	401	400
InvalidMimeType	400	415
InvalidRange	416	400
InvalidRequest	400	400, 404, 409
InvalidSignature	403	400
InvalidUploadSignature	403	400
LockTimeout	423	503
MissingContentLength	411	400
TenantNotFound	404	400

InvalidMimeType is the row I can settle from both directions. The table says 400; the source says 415; my live upload of a text/plain file into a WebP-only bucket returned a body reading "statusCode":"415". Measurement and source agree with each other and the documentation is the odd one out.

InvalidRequest is the row that breaks the mental model. It is emitted by several factories at three different statuses: UnableToEmptyBucket raises it as 409, RelatedResourceNotFound as 404, and the rest as 400. Branching on code does not determine the status either, which is worth knowing before you build a retry policy on top of one. I have gotten that classification wrong before on a different service, and the failure mode is quiet: retryable errors get swallowed and permanent ones get retried forever.

Two surfaces on one project disagree

The same project answers correctly over a different protocol. Requesting a missing object through the S3-compatible endpoint with no credentials returns a real 403 and a real S3 XML error document, status on the wire where S3 clients expect it. The REST surface is the one that collapses to 400.

Two more asymmetries came out of the matrix. Listing objects in a bucket that does not exist returns 200 and an empty array, so a typo in a bucket name is indistinguishable from an empty bucket. That one has the same shape as a mistake I made testing policies here before, where a blocked DELETE returned 204 and I read it as success: a success status is not evidence that the thing you asked for happened. And uploading with a garbage bearer token produces AccessDenied with the message Invalid Compact JWS, not the documented InvalidJWT — that code only surfaced on the signed-URL path.

What this changes for my uploader

The rule I came away with is that response.status_code is the wrong field to read against Supabase Storage over REST, and the right one is json()["code"], with json()["statusCode"] as an integer-shaped fallback for anything the enum does not cover. The same object metadata carries a third spelling, httpStatusCode, so all three names exist in one system and mean different things. This is the second time reading Storage's own stored fields has corrected me — the last one was what a REST upload stores in cache-control, where the documented one-hour default turned out to belong to the JS client rather than the server.

I have not shipped the fix. ops/make-thumbnails.py and ops/add-product-image.py still treat every 4xx as one undifferentiated failure, which is how I got here: a duplicate upload and a file over the size limit are the same event to my code, and only one of them is safe to retry. That is the next repair in the queue, and it is not done today.

Everything measured above ran on 2026-08-15 against this blog's own Supabase project — one project, one region, one public bucket, storage server 1.69.0 — using 23 deliberately malformed requests over the REST endpoints, cross-checked with curl for five of them. The source figures come from parsing codes.ts and renderable.ts at the v1.69.0 tag, which is byte-identical to master today. Limits I want stated plainly: I reached 11 of the 57 codes, so the rest of the comparison table is source reading rather than observation; I never tested a private bucket, so the RLS path is unexercised; the live 416 on a bad Range header did not come from the InvalidRange factory, which is defined as 400, and I could not locate what produced it; I have no explanation for the 200 on listing a missing bucket; and I read storage-js rather than running it, since this stack is Python and curl. My first pass at the source comparison was wrong: I paired codes to statuses with a regex that assumed adjacency, which mis-attributed InvalidRequest, and the table above comes from a second parse that walks each factory entry. The probe object was deleted afterward and the 138 rows in post_images were untouched. Full notes are in projects/blog-en/research/supabase-storage-error-codes.md.