Fix browser upload CORS and signature errors
A browser upload to cdn22.net has several separate stages, and each one fails in its own way. This guide helps you work out which stage failed before you change anything. It covers the flow described in the upload file guide.
Every error text, response and log line below is synthetic and illustrative. None of it comes from a current cdn22 incident. The two AWS pages linked in the limits section describe general AWS behavior, not any cdn22 case.
The six stages
A failure at one stage looks like a failure at another when you only read the browser console. Name the stage first.
| Stage | Who calls whom | What a failure looks like |
|---|---|---|
| 1. Account and API authorization | Your server calls the cdn22.net API | 401 for a missing or invalid key. 403 when the account is not active or you lack folder permission. These are API responses, not bucket CORS. |
| 2. Presign | Your server calls POST /v1/files/{folderId} | 400 for a bad filesMetadata item, a file over 5,000,000,000 bytes or more than 100 files. Success returns a urls array. |
| 3. Browser preflight | The browser sends OPTIONS to the storage host | If it fails, the browser never sends the PUT. The console shows a CORS message. |
| 4. Raw-byte PUT | The browser sends the file bytes to the presigned URL | A storage HTTP status such as 403 for an expired URL or signature mismatch. It may be hidden behind a CORS message. |
| 5. Confirm | Your server calls POST /v1/files/confirm-upload | success and confirmed. No delivery URL, and no check of the stored bytes. |
| 6. Public or private delivery | Readers open a CDN link, or your server asks for a signed link | Scanning, expiry and account state can still affect delivery after a successful confirm. |
Stages 1 and 2: authorization and presign
Your browser app calls its own backend. Your backend is the only place that holds the API key. It sends the raw key in the Authorization header of API POST calls, with no Bearer prefix, and never forwards it to the browser or to the storage PUT.
A 401 or 403 from the API is an account or permission problem. It is not bucket CORS, and changing storage settings cannot fix it. The presign call takes a filesMetadata array of name, size and type. An empty type becomes application/octet-stream at presign, so send the same normalized value on the PUT. A single PUT over 5,000,000,000 bytes is rejected and needs multipart upload. Create and confirm each take at most 100 files per call.
The fragment below is illustrative only. It omits authentication of your own caller, authorization, input validation and response validation. A real backend must enforce them before returning an upload URL. It is not a complete or secure handler.
// Synthetic example. Server-side only. The key never reaches the browser.
const res = await fetch("https://api.cdn22.net/v1/files/" + folderId, {
method: "POST",
headers: {
Authorization: process.env.CDN22_API_KEY, // raw key, no Bearer prefix
"Content-Type": "application/json",
},
body: JSON.stringify({
filesMetadata: [
{
name: file.name,
size: file.size,
type: file.type || "application/octet-stream",
},
],
}),
});
const body = await res.json();
// Return only what the browser needs: entry.url and entry.id.
// Do not log entry.url. It carries a signature in its query string.Scroll the code block to read long lines.
// Synthetic response shape, not an observed cdn22 incident.
{
"success": true,
"urls": [
{
"url": "<presigned upload URL, treat as a secret>",
"id": "<file uuid>",
"key": "<owner>/<folder>/report.pdf",
"private": false,
"expiresAt": null,
"duplicate": false
}
]
}Scroll the code block to read long lines.
Check duplicate before you upload. If it is true, the file may already be uploaded, so do not run a new PUT blindly. Look at the returned private value and your folder permissions to see how the file will be delivered. Do not add a per-file private flag to a filesMetadata item, because that field is not supported there.
Stage 3: browser preflight
A cross-origin PUT needs a preflight because PUT is not a CORS-safelisted method. That holds even without a Content-Type header. Access-Control-Request-Headers lists only request header names that are not CORS-safelisted. A Content-Type of application/octet-stream needs that allowance and is listed, while a value such as text/plain may not be. The PUT needs the preflight either way. The browser builds the OPTIONS request and its Origin and Access-Control headers itself.
# Synthetic illustration of what the browser sends on its own.
# Example for a PUT with Content-Type: application/octet-stream, not universal.
# Your code does not write this request and cannot repair a failure here.
OPTIONS <presigned upload URL path>
Origin: https://app.example.test
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: content-typeScroll the code block to read long lines.
First check the request host, your page origin and the stage. If the OPTIONS request went to the storage host and the response has an absent or mismatched allow response for your origin, method or header, the browser blocks the PUT and it is never sent. That points at the operator-controlled storage CORS policy. A plain network error with no response stays unknown. A failure against your own backend does not show the root cause, so check your integration, its CORS and auth settings and the transport separately. Your client code cannot repair the storage policy. Setting an Access-Control-Allow-Origin request header is not a fix, because that header belongs in the server response. The bucket CORS rules are operator controlled. Do not hide the failure by changing the request mode or turning off browser security checks, and do not ask for an allow-everything policy. Report the origin and stage to support instead.
Stage 4: the raw-byte PUT
The PUT sends the file bytes as the body, not form data. Use the presigned URL exactly as returned. Do not edit its path or query, and do not add an API key or other credentials to the request.
// Synthetic example. Runs in the browser with the URL your backend returned.
// No Authorization header here. The storage host does not use the API key.
const type = file.type || "application/octet-stream"; // same value as presign
const res = await fetch(entry.url, {
method: "PUT",
headers: { "Content-Type": type },
body: file, // raw bytes, not FormData
});
if (!res.ok) {
// Keep the stage and status. Do not retry with a new presign automatically.
throw new Error("upload stage failed, status " + res.status);
}Scroll the code block to read long lines.
When the PUT reaches storage and fails with a status, check each of these: was the URL changed, does the method differ, does a header differ from what was signed, does the content type differ from the presign value, or has the URL expired? Check each of these before you conclude anything, and treat what remains as unknown. The source asks for a 600 second URL lifetime, but the credentials or policy used to sign it can shorten the real validity. Do not confuse this with the per-file expiresAt value, which is a file lifetime and has nothing to do with how long the upload URL works.
Which headers a given URL signs depends on how it was created. A matching Content-Type removes one cause and does not fix every signature error. If a storage 403 is hidden behind a CORS message, or you see a network error with no status, the cause is unknown until you have more evidence. Stop at that point. Do not request a new presign or retry the PUT automatically.
Example errors by stage
These examples are labelled synthetic and illustrative. The API texts follow the current Express source. The AWS-style texts follow general AWS behavior and are not observed cdn22 incidents. A blocked preflight in the console (stage 3) is a different thing from a storage HTTP 403 on the PUT (stage 4): in the first the PUT is never sent, in the second storage answered. The API 401, 403 and confirm 400 below are not storage CORS, so changing bucket settings cannot fix them.
# Synthetic and illustrative. Not observed cdn22 incidents, and the AWS-style
# texts are not a guaranteed response. Nothing here came from a real request.
Stage 1, API response, HTTP 401: {"error":"API key required."}
Stage 1, API response, HTTP 403: {"error":"Account locked. Add credits to restore API access."}
Stage 3, browser console, no HTTP status for the PUT: blocked by CORS policy, no 'Access-Control-Allow-Origin' header is present on the requested resource
Stage 4, AWS-style storage response, HTTP 403: <Error><Code>SignatureDoesNotMatch</Code></Error>
Stage 4, AWS-style storage response, HTTP 403: <Error><Code>AccessDenied</Code><Message>Request has expired</Message></Error>
Stage 5, API response, HTTP 400: {"success":false,"message":"ids array required."}Scroll the code block to read long lines.
Next safe check: for a stage 1 status, check the key and account state on your server. For stage 3, note the request host and origin and compare against the operator policy. For stage 4, check the URL, method, content type and age, without printing the URL. For stage 5, check the ids you send. Make no new presign or PUT until you know which stage failed.
Comparing curl with the browser
A curl request does not run a preflight or apply the same-origin rules, so it is not a browser CORS test. A curl success does not show that your page origin is allowed, and a curl failure does not show that CORS is the cause. If you compare them, keep the presigned URL and the API key out of command arguments, shell history and logs, and avoid verbose output, tracing, HAR exports and the browser copy as curl action, which all capture the signed URL. This guide gives no upload curl command for that reason.
Stage 5: confirm
After a PUT you know succeeded, your server calls POST /v1/files/confirm-upload with an ids array of 1 to 100 UUIDs. The response has success and confirmed only.
// Synthetic example. Server-side, after a PUT you know succeeded.
// POST /v1/files/confirm-upload body: { "ids": ["<uuid>"] } (1 to 100 UUIDs)
{ "success": true, "confirmed": 1 } // the one file was marked uploaded
{ "success": true, "confirmed": 0 } // already confirmed, or nothing pendingScroll the code block to read long lines.
In the current service confirm marks pending rows as uploaded and does not verify the stored bytes. A confirmed value of 0 can mean the rows were already confirmed, so it is not proof that your first upload worked. If the PUT outcome is unknown, such as a network failure with no status, do not confirm. Reconcile first, without an automatic new presign, PUT or retry. Files that are never confirmed are removed by a cleanup job after 24 hours with the default setting.
Stage 6: delivery
For a public file, build the CDN link from the returned key, as in https://cdn.cdn22.net/<key>. Do not take it from the presigned URL, and do not look for a field the confirm response does not have. For a private file, your server asks for a signed link with GET /v1/files/signed/{id} using the API key, and the browser only receives the resulting link. Confirmation is not a delivery guarantee. Scanning, expiry and account state still matter.
What you control and what support controls
The storage bucket, its CORS rules and its signing configuration are controlled by the operator. You control your file metadata, the exact request bytes and headers, your backend authorization, and whether you leave the signed URL unmodified. For a report, send a sanitized summary like this and nothing more.
Stage: raw-byte PUT
Status: 403 (or "not visible, console shows CORS")
Request ID: <value from the response headers, if visible>
Time (UTC): 2026-11-14T10:22:05Z
Page origin: https://app.example.test
# Never include the full upload URL, its query string, the object key,
# the API key or any customer data.Scroll the code block to read long lines.
Limits of this guide
General AWS behavior is described in the AWS guide to presigned URLs and the AWS article on signature mismatch. They are general references and not evidence of a cdn22 incident. Background terms are in the CORS and presigned URL glossary entries. Causes this page cannot show from your evidence stay unknown.
FAQ
Is a CORS error in the console always a bucket CORS problem?
No. Start with the request host, the page origin and the stage. If the failed OPTIONS request went to the storage host and its response has an absent or mismatched allow response for your origin, method or header, that points at the operator-controlled storage CORS policy, and the PUT is never sent. If the request went to a different host, such as your own backend, a different host is not proof of the cause: investigate your own backend, its CORS and auth settings and the transport separately. A plain network error, a wrong target or a transport problem stays unknown. A browser also hides the response of a cross-origin request that lacks the right headers, so a storage HTTP 403 such as an expired or mismatched signature can appear as a CORS message. Read the status and request ID where they are visible.
Does a matching Content-Type fix every signature error?
No. The presign step uses the type you supply, or falls back to application/octet-stream when it is empty. It does not detect a type from the name or size. Sending the same value on the PUT avoids a content-type mismatch. An expired URL, a changed URL, the wrong method or extra headers can still fail, and this guide does not claim to cover every case.
Can I fix a CORS error from my app code?
Only the part that is yours. You can fix your own backend, your file metadata and the exact bytes and headers you send. You cannot change the operator-controlled storage CORS policy from client code, and the browser adds Origin and the preflight headers itself. Adding an Access-Control-Allow-Origin header to your request does nothing useful, because that is a response header set by the server. If the evidence points at the storage policy, report it to support with the sanitized summary below.
Where does the API key go?
Only on your server. The upload flow API POST calls send it in the Authorization header as the raw key with no Bearer prefix. For a private file, your server also makes a server-side authenticated GET to /v1/files/signed/{id} with the same raw key and passes only the resulting link on. Never put the key in browser code, and never add it to the PUT to the presigned storage URL. The browser should call your own authenticated backend, which calls cdn22.net.
Does confirm prove the bytes arrived?
No. The confirm response contains success and a confirmed count, and no delivery URL. In the current service it marks pending rows as uploaded and does not check the stored bytes. A confirmed value of 0 can mean the files were already confirmed, so it does not prove your first upload worked. Confirm only after a PUT you know succeeded.
What happens to files I never confirm?
A cleanup job removes unconfirmed rows after 24 hours with the default setting. The operator can configure that window, so treat 24 hours as the default, not a promise.
Get an API key
Create an account, make a folder and an API key, and keep the key on your server.