Fix jQuery $.ajax CORS errors

The error: status 0 and an empty response

jQuery uses XMLHttpRequest, and the browser gives XMLHttpRequest no detail about a cross-origin response it refused to deliver: the request errors with status 0, which is the same value you get for a network failure or an aborted request. Open the browser console: a CORS block names the URL, your origin and the missing or wrong header. Status code: 200 in the Firefox version of the message means the server answered and only the header was missing, which is the normal case for a public API that was never meant for browsers.

$.getJSON('https://store.steampowered.com/api/appdetails?appids=440')
  .fail(function (jqXHR, textStatus, errorThrown) {
    console.log(jqXHR.status);       // 0
    console.log(textStatus);         // "error"
    console.log(errorThrown);        // ""
    console.log(jqXHR.responseText); // undefined
  });

// The reason is only in the browser console:
// Access to XMLHttpRequest at 'https://store.steampowered.com/api/appdetails?appids=440'
// from origin 'https://www.yoursite.com' has been blocked by CORS policy:
// No 'Access-Control-Allow-Origin' header is present on the requested resource.

jQuery options that do not help

• crossDomain: true only tells jQuery to treat the request as cross-origin, which it already detects from the URL. It changes no header and asks the browser for no permission.
• headers: { ... } with anything beyond Accept and a simple Content-Type turns the call into a preflighted request: the browser sends OPTIONS first, and an API that ignores OPTIONS now fails twice. See response to preflight request doesn't pass access control check.
• xhrFields: { withCredentials: true } makes things stricter: the response must then name your exact origin, not *, and add Access-Control-Allow-Credentials: true. Leave it off unless the API uses cookies you own.
• dataType: 'jsonp' is not a CORS workaround for arbitrary APIs; it loads the URL as a script tag, so the server must wrap its JSON in your callback function. APIs without that answer plain JSON and the browser reports a syntax error.
• Setting Access-Control-Allow-Origin in the request is meaningless: it is a response header, and only the server can send it.

Public APIs: prefix a proxy

When the API is not yours, the header has to come from somewhere else. A CORS proxy fetches the API from its own servers and relays the response with Access-Control-Allow-Origin set to your origin. With cors.dev the change is the URL and nothing else in your $.ajax call. The example reads the Steam store API, which returns JSON and sends no CORS header.

var PROXY = 'https://proxy.cors.dev/';

$.ajax({
  url: PROXY + 'https://store.steampowered.com/api/appdetails?appids=440',
  dataType: 'json',
  xhrFields: { withCredentials: false },
})
  .done(function (data) {
    var game = data['440'].data;
    $('#game').text(game.name + (game.is_free ? ' is free to play' : ' is a paid game'));
  })
  .fail(function (jqXHR) {
    // X-Cors-Error is set when the proxy refused or could not complete the request
    var code = jqXHR.getResponseHeader('X-Cors-Error') || jqXHR.status || 'network error';
    $('#game').text('Could not load the game: ' + code);
  });

Anonymous requests cover GET and HEAD to any public HTTPS host and forward only Accept, If-None-Match and If-Modified-Since; cookies are never forwarded, so withCredentials stays false. Responses keep the upstream status and Content-Type, so dataType: 'json' and dataType: 'xml' behave as they would against the API directly. A proxy-side failure sets X-Cors-Error, for example response_too_large above 1 MiB.

JSONP: still fine for the APIs that offer it

Before CORS existed, APIs offered JSONP: you pass a callback name and the server answers callback({...}) as a script. jQuery handles the plumbing when you set dataType: 'jsonp'. It still works where supported, GET only, and it runs whatever the server returns as code on your page, so use it for sources you trust.

// Works: the MediaWiki API wraps the JSON in your callback function
$.ajax({
  url: 'https://en.wikipedia.org/w/api.php',
  data: { action: 'query', prop: 'extracts', exintro: 1, titles: 'JQuery', format: 'json' },
  dataType: 'jsonp',
}).done(function (data) {
  console.log(Object.values(data.query.pages)[0].extract);
});

// Does not work: an API without JSONP support answers plain JSON,
// the browser tries to run it as a script and reports "Unexpected token ':'"

Your own API: send the headers

If you control the server, add Access-Control-Allow-Origin for your site origin (or * for public data), list the methods and request headers your calls use, and answer OPTIONS with 204. Framework guides: Express, Flask, Django, Laravel, Spring Boot. The full header reference is in CORS headers list.

Limits and pricing

Good questions.