◆Error Codes Wiki

HTTP OPTIONS Preflight Errors — CORS Preflight Request Failures

Error4xx client error

Overview

Fix HTTP OPTIONS preflight request failures causing CORS errors, including missing headers, incorrect methods, and proxy blocking preflight requests.

Key Details

  • Preflight requests are automatic OPTIONS requests sent by browsers before cross-origin requests with custom headers or methods
  • The server must respond to OPTIONS with appropriate Access-Control-Allow-* headers
  • Preflight is triggered by non-simple requests: custom headers, PUT/PATCH/DELETE methods, or non-standard Content-Types
  • A failed preflight blocks the actual request entirely — the browser never sends it
  • Preflight responses can be cached using Access-Control-Max-Age to reduce repeated OPTIONS calls

Common Causes

  • Server not handling OPTIONS method — returning 405 Method Not Allowed instead of CORS headers
  • Access-Control-Allow-Headers missing the custom header names used in the request
  • Access-Control-Allow-Methods not including the HTTP method (PUT, PATCH, DELETE) being used
  • Reverse proxy or WAF blocking OPTIONS requests before they reach the application

Steps

  1. 1Add an OPTIONS route handler that returns 204 with Access-Control-Allow-Origin, Allow-Methods, and Allow-Headers
  2. 2Ensure Access-Control-Allow-Headers includes all custom headers: Authorization, Content-Type, X-Requested-With, etc.
  3. 3Set Access-Control-Allow-Methods to include all methods your API uses: GET, POST, PUT, PATCH, DELETE, OPTIONS
  4. 4Add Access-Control-Max-Age: 86400 to cache preflight results and reduce OPTIONS requests
  5. 5Configure your reverse proxy to pass OPTIONS requests through to the application server

Tags

corspreflightoptionscross-originheaders

More in 4xx Client Error

http-400-bad-requestHTTP 400 Bad Request — What It Means & How to Fix It
Error
http-401-unauthorizedHTTP 401 Unauthorized — What It Means & How to Fix It
Error
http-402-payment-requiredHTTP 402 Payment Required — What It Means & How to Fix It
Error
http-403-forbiddenHTTP 403 Forbidden — What It Means & How to Fix It
Error
http-404-not-foundHTTP 404 Not Found — What It Means & How to Fix It
Error
http-405-method-not-allowedHTTP 405 Method Not Allowed — What It Means & How to Fix It
Error

Frequently Asked Questions

Browsers send preflight for requests with custom headers (Authorization, X-*), non-simple methods (PUT, PATCH, DELETE), or Content-Type other than application/x-www-form-urlencoded, multipart/form-data, or text/plain.