Understanding CORS: Cross‑Origin Resource Sharing, Simple and Preflight Requests, and Common Errors

In a web front‑end/back‑end separated architecture, cross‑origin (CORS) requests are common; browsers restrict JavaScript from making cross‑origin HTTP requests unless the server explicitly permits them via the CORS protocol.

CORS (Cross‑Origin Resource Sharing) is a W3C standard composed of specific HTTP headers that tell the browser whether a cross‑origin request may be fulfilled, allowing resources to be shared safely between different origins.

The origin header identifies the request’s scheme, host, and port. Valid forms include origin: null , origin: <scheme>://<hostname> , and origin: <scheme>://<hostname>:<port> .

Same‑origin is defined when two URLs share the same scheme, host, and port; otherwise they are considered cross‑origin. A table of URL examples illustrates various same‑origin and cross‑origin cases.

Simple Request

A request is classified as a simple request when all of the following are true:

HTTP method is GET, POST, or HEAD.

Only allowed request headers are used (e.g., accept , accept-language , content-language , content-type with values text/plain , multipart/form-data , or application/x-www-form-urlencoded ).

No custom event listeners are registered on the XMLHttpRequest object.

No ReadableStream is used.

Example of a simple CORS request:

const xhr = new XMLHttpRequest();
const url = 'https://api.box3.cn/example/simple';
xhr.open('GET', url);
xhr.send();

The browser sends a request with an origin header and receives a response containing access-control-allow-origin: * , indicating the resource is publicly accessible.

Preflight Request

When a request does not meet the simple‑request criteria, the browser automatically issues a preflight OPTIONS request to determine if the actual request is allowed. The preflight includes access-control-request-method and access-control-request-headers headers.

Example preflight‑triggering code:

const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://api.box3.cn/example/request');
xhr.setRequestHeader('box3-token', '111-222-333-444');
xhr.send();

The server responds with headers such as access-control-allow-headers: box3-token and access-control-allow-origin: * . Caching can be enabled with access-control-max-age .

Credentials

By default browsers do not send cookies with cross‑origin requests. To include credentials, set xhr.withCredentials = true . The server must then return access-control-allow-credentials: true and a specific access-control-allow-origin value (wildcard is not allowed).

const xhr = new XMLHttpRequest();
const url = 'https://api.box3.cn/example/simple_cookie';
xhr.open('GET', url);
xhr.withCredentials = true;
xhr.send();

Common CORS Errors

Typical misconfigurations that cause CORS failures include:

Incorrect access-control-allow-origin value.

Missing or incomplete access-control-allow-methods .

Missing or incomplete access-control-allow-headers .

Improper access-control-allow-credentials settings.

Redirects on preflight requests also trigger errors because the preflight response must have a 2xx status.

HTTP Header Reference

Key request headers: origin , access-control-request-method , access-control-request-headers . Key response headers: access-control-allow-origin , access-control-expose-headers , access-control-allow-methods , access-control-allow-headers , access-control-max-age , access-control-allow-credentials .