CORS proxy for POST, PUT, PATCH and DELETE

Why a cross-origin POST fails

A POST with Content-Type: application/json, an Authorization header or any custom header, and every PUT, PATCH and DELETE, makes the browser send an OPTIONS preflight first. The API has to answer it with Access-Control-Allow-Methods and Access-Control-Allow-Headers that cover your request, then send Access-Control-Allow-Origin on the real response. Most third-party APIs do neither, so the request fails in the browser while it works in curl or Postman. CORS preflight failed walks through the error messages.

The anonymous cors.dev proxy relays GET and HEAD only: a POST gets 405 with X-Cors-Error: method_not_allowed and Allow: GET, HEAD, OPTIONS, and a GET with a body gets 400. Writes go through a trial or Pro Connection.

Send a JSON POST, PATCH or DELETE

Create a Connection in the dashboard with your app origin, such as https://app.example.com or http://localhost:5173, and the API host, such as api.example.com. Then call the proxy with any method and send the Connection key in X-Cors-Key. Method, body and headers stay your normal fetch call.

const PROXY = 'https://proxy.cors.dev/';
const headers = {
  'X-Cors-Key': 'YOUR_CONNECTION_KEY',
  'Content-Type': 'application/json',
  Authorization: `Bearer ${accessToken}`,
};

const created = await fetch(PROXY + 'https://api.example.com/v1/items', {
  method: 'POST',
  headers,
  body: JSON.stringify({ name: 'New item' }),
  credentials: 'omit',
});
const item = await created.json(); // a 201 from the API arrives as 201

await fetch(PROXY + `https://api.example.com/v1/items/${item.id}`, {
  method: 'PATCH', // capitals: fetch does not uppercase PATCH for you
  headers,
  body: JSON.stringify({ name: 'Renamed' }),
  credentials: 'omit',
});

const removed = await fetch(PROXY + `https://api.example.com/v1/items/${item.id}`, {
  method: 'DELETE',
  headers,
  credentials: 'omit',
});
if (!removed.ok) {
  throw new Error(`HTTP ${removed.status}: ${removed.headers.get('X-Cors-Error') ?? 'upstream error'}`);
}

What happens to the preflight

The proxy answers every OPTIONS preflight itself with a 204: Access-Control-Allow-Methods: GET, HEAD, POST, PUT, PATCH, DELETE, the request headers you asked for echoed back, your exact origin in Access-Control-Allow-Origin and Access-Control-Max-Age: 600, so the browser reuses that answer for 10 minutes. The API never sees the OPTIONS request, and preflights do not count toward your monthly requests.

Browsers never put custom headers on a preflight, so the key, origin and host checks run on the real request that follows. A preflight can pass while that request fails with 401 invalid_key, 403 origin_not_allowed or 403 target_not_allowed: read the X-Cors-Error header on the second request.

Bodies, responses and status codes

• Request bodies up to 1 MiB in any format: JSON, URL-encoded or multipart forms, plain text or binary. A larger body gets 413 request_too_large.
• Responses of any content type up to 6 MiB, with the API status unchanged: a 201, 204, 409 or 422 reaches your code as it was sent, marked X-Cors-Source: upstream. Response headers such as ETag and X-RateLimit-Remaining are readable from JavaScript.
• The API gets 10 seconds to answer. After that the proxy returns 504 upstream_timeout, and the write may or may not have happened on the API side.
• Writes are sent once, never retried and never cached. X-Cors-Cache works on GET only, and a POST that sends it gets 400.
• Redirects are followed for up to 4 hops when every hop host is on your Connection. A redirect to another host that would resend the body fails with 502 redirect_not_supported rather than sending your body to a new host.
• Cookies never travel and upstream Set-Cookie headers are stripped. Use credentials: 'omit': with credentials: 'include' the browser blocks the response, because the proxy never sends Access-Control-Allow-Credentials.

Free vs Pro for write requests

Errors you can hit on a write

• 405 method_not_allowed: the request had no X-Cors-Key or the account has no active trial or Pro, so the GET-only rules applied, or the preflight asked for a lowercase method.
• 401 invalid_key: the key is malformed, unknown or revoked.
• 403 origin_not_allowed: the page origin is not on the Connection. Compare scheme, host and port.
• 403 target_not_allowed: the API host, or a redirect hop, is not on the Connection.
• 413 request_too_large: the body is over 1 MiB.
• 429 rate_limited: wait the seconds in Retry-After. 429 quota_exceeded: the billing period is used up; add 500,000 requests for $5.
• 502 response_too_large or redirect_not_supported, 504 upstream_timeout: the API sent more than 6 MiB, redirected the body elsewhere or took longer than 10 seconds.

Good questions.