Blog
CORS Errors During API Onboarding
Browsers hide CORS failures from your API logs and from the developer. The console says the request was blocked. Your server may have returned 401. Name both, and do not make them file a ticket to discover which.
2026-07-16 · 7 min read · AethelLayer
The browser ate the status
A failed preflight looks like a network error in application code. The real status might be a missing header, a 401 on OPTIONS, or an origin you did not allow. The developer sees one red line in DevTools and assumes your API is down.
Document the exact header you require and the origins you allow for the sample. 'Enable CORS' is not a fix they can apply.
OPTIONS is a real route
If your auth middleware rejects OPTIONS, every browser sample dies before the POST. Allow the preflight without a bearer token, and keep the bearer check on the actual call.
Return the error code in a header the browser is allowed to read. Otherwise your careful JSON body never reaches the page.
Server-side samples avoid this, and hide a different bug
A Node quickstart will not show CORS at all. Offer one browser sample and one server sample, and label which errors exist only in the browser. Evaluators who start in the browser are the ones you lose.
Capture the origin and the route template when your API rejects a preflight. Do not capture cookies.
Put the allowed origin in the message
If you reject the origin, say which origin you saw and which list you checked. Developers pointing a Vite port at a production allow-list need that sentence, not a specification quote.
A week of the same origin in drafts is a one-line allow-list change or a README that names the port.
Keep reading
Capture the failure before they leave
Capture the failure before they leave. Book early access or talk to sales, then install @aethellayer/sdk when you are onboarded.