Simple vs Preflight Requests: CORS Mechanics

Without correct preflight handling, browsers silently block cross-origin API calls before a single byte of payload is transmitted — and the resulting console error gives almost no indication of which server header is missing. This page is part of Core CORS Mechanics & Same-Origin Policy Fundamentals and covers the exact classification rules the browser applies, the full negotiation lifecycle, per-stack server configuration, and a systematic debugging checklist.

The classification decision the browser makes before every cross-origin request

The WHATWG Fetch Standard (§3.1 “CORS-safelisted request-header”) defines a deterministic algorithm the browser runs on every outgoing cross-origin fetch. If the request passes all three criteria it is dispatched directly — no prior negotiation. If any criterion fails the browser intercepts the request and sends an OPTIONS preflight first.

Request classification reference table

The credentials: 'include' flag or withCredentials: true on XHR does not itself change the classification. The method and header criteria still govern whether a preflight fires. When credentials are present, however, the server must echo the exact Origin — it cannot respond with Access-Control-Allow-Origin: *.

Code examples: same payload, different classification

// Simple request — dispatched immediately, no preflight
fetch('https://api.example.com/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({ q: 'cors' })
});

// Preflight required — application/json is not safelisted
fetch('https://api.example.com/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Trace-Id': 'abc123'           // non-safelisted header also triggers preflight
  },
  body: JSON.stringify({ q: 'cors' })
});

// Preflight required — PUT is not a safelisted method
fetch('https://api.example.com/resource/42', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'active' })
});

For the spec-level rationale behind why the browser uses OPTIONS for the preflight rather than a synthetic internal check, see Why Preflight Requests Use the OPTIONS Method.

Preflight negotiation lifecycle

When a request fails the simple-request test, the browser intercepts execution, constructs an OPTIONS request, and withholds the actual request until the server responds correctly. The entire sequence is invisible to application JavaScript — there is no callback, no event, no way to inspect or cancel it.

The four-step exchange

1. Browser dispatches OPTIONS. The request carries Origin, Access-Control-Request-Method (the intended method), and Access-Control-Request-Headers (a comma-separated list of every non-safelisted header the actual request will send).
2. Server validates and responds. The server must return 204 No Content or 200 OK with Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers. A missing or mismatched header is treated as denial.
3. Browser evaluates the response. The browser checks that its requested method and headers are present in the server’s allow lists. It also reads Access-Control-Max-Age to determine how long to cache this grant.
4. Browser dispatches the actual request. If validation passes, the real request fires with its full headers and body. If validation fails, the browser raises a network error and JavaScript sees only an opaque failure — the payload is never sent.

Preflight response header reference

Access-Control-Max-Age controls how long the browser reuses a cached preflight response before sending a fresh OPTIONS. Chrome’s hard cap is 7,200 seconds (2 hours); Firefox allows up to 86,400 seconds (24 hours). Setting the value beyond the browser’s cap has no additional effect. For a full treatment of tuning this header, see Cache Duration Tuning with Access-Control-Max-Age.

Step-by-step server implementation

1. Express / Node.js

import express from 'express';

const app = express();
const ALLOWED_ORIGINS = new Set([
  'https://app.example.com',
  'https://admin.example.com'
]);

// Preflight handler — must match before any body-parsing middleware
app.options('*', (req, res) => {
  const origin = req.headers.origin;

  if (!ALLOWED_ORIGINS.has(origin)) {
    // Do not set any CORS headers; let the browser see a plain 403
    return res.sendStatus(403);
  }

  res.setHeader('Access-Control-Allow-Origin', origin);
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH');
  // Echo back exactly what the browser asked for to avoid header mismatch
  const requestedHeaders = req.headers['access-control-request-headers'] || '';
  res.setHeader('Access-Control-Allow-Headers', requestedHeaders);
  res.setHeader('Access-Control-Max-Age', '600');
  res.setHeader('Vary', 'Origin');
  return res.sendStatus(204);
});

// Attach CORS headers to every actual response as well
app.use((req, res, next) => {
  const origin = req.headers.origin;
  if (origin && ALLOWED_ORIGINS.has(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Vary', 'Origin');
  }
  next();
});

app.get('/api/data', (_req, res) => res.json({ ok: true }));
app.listen(3000);

Reflecting Access-Control-Request-Headers verbatim eliminates header-mismatch errors when the frontend adds new custom headers. Apply the same dynamic origin validation patterns to the actual-request middleware so the two stay in sync. Note that Vary: Origin is mandatory on any response whose Access-Control-Allow-Origin value depends on the incoming Origin — omitting it lets CDNs serve a cached response from one origin to a different one.

2. Nginx

# /etc/nginx/conf.d/api.conf

map $http_origin $cors_origin {
  default           "";
  "https://app.example.com"   $http_origin;
  "https://admin.example.com" $http_origin;
}

server {
  listen 443 ssl;
  server_name api.example.com;

  location /api/ {
    # Preflight branch
    if ($request_method = 'OPTIONS') {
      add_header 'Access-Control-Allow-Origin'  $cors_origin always;
      add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, PATCH' always;
      add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-Trace-Id' always;
      add_header 'Access-Control-Max-Age'       600 always;
      add_header 'Vary'                         'Origin' always;
      return 204;
    }

    # Actual request — attach CORS headers here too
    add_header 'Access-Control-Allow-Origin' $cors_origin always;
    add_header 'Vary' 'Origin' always;

    proxy_pass http://backend_upstream;
  }
}

The map directive computes $cors_origin once per request: an allowed origin passes through unchanged; anything else resolves to an empty string, so no Access-Control-Allow-Origin header is emitted. For multiple-origin scenarios, see Configuring CORS in Nginx for Multiple Origins.

3. Fetch API (service worker or edge middleware)

// Cloudflare Worker or Deno edge function
export default {
  async fetch(request) {
    const ALLOWED = new Set(['https://app.example.com', 'https://admin.example.com']);
    const origin = request.headers.get('Origin') || '';

    if (request.method === 'OPTIONS') {
      if (!ALLOWED.has(origin)) {
        return new Response(null, { status: 403 });
      }
      return new Response(null, {
        status: 204,
        headers: {
          'Access-Control-Allow-Origin': origin,
          'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
          'Access-Control-Allow-Headers':
            request.headers.get('Access-Control-Request-Headers') || '',
          'Access-Control-Max-Age': '600',
          'Vary': 'Origin'
        }
      });
    }

    const response = await fetch(request);
    const modified = new Response(response.body, response);
    if (ALLOWED.has(origin)) {
      modified.headers.set('Access-Control-Allow-Origin', origin);
      modified.headers.set('Vary', 'Origin');
    }
    return modified;
  }
};

Edge cases and security boundaries

Credentials and the wildcard prohibition

When a request includes credentials: 'include' (Fetch) or withCredentials: true (XHR), the server must not respond with Access-Control-Allow-Origin: *. Browsers will block the response with a hard failure regardless of any other headers. The server must echo the exact Origin value. This rule applies to both the preflight response and the actual response — setting it correctly on one and using * on the other still causes a failure. Full credential isolation rules are covered in Credential Sharing & Security Boundaries.

Null origin from sandboxed iframes

An <iframe sandbox> without allow-same-origin causes the browser to send Origin: null for cross-origin requests originating inside it. Reflecting null in Access-Control-Allow-Origin is unsafe because any sandboxed context — including a malicious one — can generate a null-origin request. Validate null origins with extreme care or reject them outright.

Subdomain normalization

https://sub.example.com and https://example.com are different origins per the origin matching rules. A server that strips the subdomain and matches against the base domain will accept requests from any subdomain, including ones that may be compromised. Always match the full origin string.

Opaque responses

A fetch(url, { mode: 'no-cors' }) call returns an opaque response — the browser suppresses all headers and status. JavaScript cannot read the response body or status. Opaque responses do not trigger preflights, but they also provide no usable data. They are appropriate only for fire-and-forget side effects such as analytics pings.

The Access-Control-Request-Headers matching rule

Header name comparison in CORS is case-insensitive per the Fetch Standard. A server that returns Access-Control-Allow-Headers: authorization will satisfy a browser preflight that sends Access-Control-Request-Headers: Authorization. However, header list ordering is irrelevant — the browser matches by set membership, not position.

Proxy and CDN interaction

Preflight responses are HTTP responses like any other and are subject to CDN caching unless explicitly excluded.

What goes wrong: A CDN caches the first preflight response. The server’s allowlist is then updated to add a new origin. The CDN continues serving the stale cached preflight to requests from the new origin, which sees a response for the wrong origin value and fails.

Fix: Add Vary: Origin to preflight responses. This instructs the CDN to maintain a separate cache entry per requesting origin. Without it, the CDN folds all preflight responses into a single cache key. For a full treatment of Vary: Origin and deduplication strategies, see Header Deduplication Techniques.

Additional CDN considerations:

• Some CDN products strip OPTIONS requests and return a synthetic 200 before the request reaches the origin. Verify preflight pass-through in your CDN’s route configuration.
• Access-Control-Max-Age controls the browser cache, not the CDN cache. Use Cache-Control: no-store on preflight responses if you want to prevent CDN caching independently of the browser limit.
• When using proxy bypass strategies to route cross-origin traffic through a same-origin reverse proxy, the browser never sends a preflight because it sees all requests as same-origin.

DevTools and curl verification checklist

• Open DevTools → Network tab → filter by Fetch/XHR or type OPTIONS in the filter box
• Confirm an OPTIONS request appears before the actual request (absent means the request was classified as simple)
• Check the OPTIONS response status is 204 or 200 — a 404 or 405 means the route is not handled
• Confirm Access-Control-Allow-Origin in the OPTIONS response matches the page origin exactly
• Confirm Access-Control-Allow-Methods includes the method the actual request uses
• Confirm Access-Control-Allow-Headers includes every non-safelisted header the actual request sends
• Confirm Vary: Origin is present on both the preflight and actual response
• Curl the preflight manually and inspect all headers:

curl -i -X OPTIONS https://api.example.com/api/data \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: DELETE' \
  -H 'Access-Control-Request-Headers: Authorization, X-Trace-Id'

• If credentials are involved, confirm Access-Control-Allow-Credentials: true is present and Access-Control-Allow-Origin is not *
• To force a fresh preflight (clear browser cache): open DevTools → Network → check “Disable cache” → reload, or use a new private window

Common mistakes

FAQ