"CORS error" est probablement l'une des erreurs les plus mal comprises du développement web, parce qu'elle se manifeste côté client mais se corrige presque toujours côté serveur, et parce que l'erreur affichée dans la console ne décrit jamais la vraie cause avec précision. Comprendre que CORS est une politique de sécurité du navigateur, pas de l'API, change complètement la façon de la déboguer.

CORS n'est pas une protection de l'API

Le malentendu de base : CORS ne protège pas le serveur contre des requêtes malveillantes. N'importe quel outil qui n'est pas un navigateur (curl, Postman, un script backend, fetch depuis un autre serveur) ignore totalement CORS et peut appeler l'API sans restriction. CORS est une règle que le navigateur applique pour protéger l'utilisateur : il empêche un site A malveillant de lire la réponse d'une requête faite au nom de l'utilisateur vers un site B (sa banque, son email) en utilisant les cookies de session déjà présents dans son navigateur.

La requête part donc bel et bien vers le serveur dans la plupart des cas. Ce que le navigateur bloque, c'est la lecture de la réponse par le code JavaScript qui a initié l'appel, si le serveur n'a pas explicitement autorisé l'origine appelante.

Le mécanisme exact : "same-origin" et ce qui le déclenche

Deux URLs partagent la même origine si le schéma, le domaine et le port sont strictement identiques. https://app.example.com et https://api.example.com sont deux origines différentes, même si elles appartiennent à la même entreprise et au même certificat wildcard. C'est cette différence qui déclenche CORS dès que le frontend appelle l'API sur un sous-domaine distinct, un port différent en développement local (localhost:3000 vers localhost:8000), ou un domaine tiers.

La preflight request : la partie la plus mal comprise

Pour certaines requêtes, le navigateur n'envoie pas directement la requête réelle. Il envoie d'abord une requête OPTIONS, appelée preflight, pour demander au serveur s'il autorise cette combinaison de méthode, d'en-têtes et d'origine. C'est déclenché dès que la requête sort du périmètre d'une "requête simple" (GET/POST/HEAD avec un type de contenu basique et sans en-tête personnalisé) : typiquement toute requête avec Content-Type: application/json, une méthode PUT/PATCH/DELETE, ou un en-tête Authorization.

OPTIONS /api/users HTTP/1.1
Origin: https://app.example.com
Access-Control-Request-Method: PATCH
Access-Control-Request-Headers: content-type, authorization

Le serveur doit répondre avec les en-têtes qui autorisent explicitement cette combinaison, sinon le navigateur annule la vraie requête avant même qu'elle ne parte :

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
Access-Control-Allow-Headers: content-type, authorization
Access-Control-Max-Age: 86400

C'est pourquoi on voit souvent, dans l'onglet Network, une requête OPTIONS qui renvoie 200 ou 204 mais que la requête PATCH qui suit n'apparaît jamais : le navigateur l'a bloquée localement, elle n'a même pas été envoyée.

Diagnostiquer correctement

Le message d'erreur dans la console ("No 'Access-Control-Allow-Origin' header is present") décrit un symptôme, pas une cause. Avant de modifier la configuration du serveur, il faut inspecter l'onglet Network :

  1. La requête OPTIONS existe-t-elle, et que renvoie-t-elle exactement comme en-têtes ?
  2. Si elle renvoie une erreur 401/403/500, le problème n'est probablement pas CORS du tout, mais un middleware d'authentification qui s'exécute aussi sur les requêtes preflight et les rejette (un piège très fréquent).
  3. L'en-tête Access-Control-Allow-Origin renvoyé correspond-il exactement à l'origine qui appelle (schéma + domaine + port) ?
curl -i -X OPTIONS https://api.example.com/users \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: PATCH"

Cette commande reproduit exactement ce que fait le navigateur et affiche la réponse brute du serveur, sans l'ambiguïté du message de console.

Les erreurs de configuration les plus fréquentes

Access-Control-Allow-Origin: * avec des credentials

La spécification CORS interdit explicitement de combiner * avec Access-Control-Allow-Credentials: true. Si l'API doit recevoir des cookies de session ou un header Authorization, le wildcard ne fonctionne pas et le serveur doit refléter dynamiquement l'origine exacte de la requête (après l'avoir vérifiée contre une liste blanche), jamais un * littéral.

// Express - exemple de configuration correcte avec credentials
const allowedOrigins = ["https://app.example.com", "https://admin.example.com"];

app.use((req, res, next) => {
  const origin = req.headers.origin;
  if (allowedOrigins.includes(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin);
    res.setHeader("Access-Control-Allow-Credentials", "true");
  }
  next();
});

Oublier Access-Control-Expose-Headers

Même quand une requête réussit, le code JavaScript ne peut lire que les en-têtes de réponse autorisés explicitement via Access-Control-Expose-Headers. Un header custom comme X-Total-Count (fréquent pour la pagination) sera invisible côté client tant qu'il n'est pas listé, même si la requête réussit sans erreur CORS visible.

Configurer CORS au niveau applicatif alors qu'un reverse proxy renvoie déjà des en-têtes

Quand Nginx ou un API Gateway ajoute aussi ses propres en-têtes CORS en plus de ceux renvoyés par l'application (Laravel, Express, Django), le navigateur peut recevoir deux valeurs dupliquées pour Access-Control-Allow-Origin, ce qui est traité comme invalide et bloque la requête malgré une configuration qui semble correcte à chaque niveau pris isolément.

Les tradeoffs d'une configuration restrictive

Restreindre Access-Control-Allow-Origin à une liste blanche précise est la bonne pratique, mais elle a un coût opérationnel réel : chaque nouvel environnement (preview de PR, nouveau sous-domaine client, environnement de staging) doit être explicitement ajouté à la liste, ou la configuration doit être pilotée par variable d'environnement plutôt que codée en dur. Beaucoup d'équipes cèdent à * par lassitude ; c'est acceptable pour une API publique en lecture seule sans cookies ni authentification par header sensible, jamais pour une API qui manipule des sessions ou des données utilisateur.

Quand CORS n'est pas vraiment le problème

Si la requête échoue avec une erreur réseau générique (Failed to fetch, pas de message CORS explicite) et qu'aucune requête n'apparaît même dans l'onglet Network, le problème est souvent ailleurs : certificat TLS invalide, serveur injoignable, Mixed Content (page HTTPS appelant une ressource HTTP), ou Content Security Policy qui bloque la requête avant même qu'elle n'atteigne la logique CORS. Ajouter des en-têtes CORS ne résout rien dans ces cas, et perdre du temps à itérer sur la configuration CORS alors que la requête ne part jamais du navigateur est l'erreur de diagnostic la plus fréquente sur ce sujet.

Le piège du cache CDN et de l'en-tête Vary

Quand une réponse passe par un CDN ou un cache HTTP intermédiaire (Cloudflare, Varnish, un cache applicatif), et que le serveur reflète dynamiquement l'origine appelante dans Access-Control-Allow-Origin, il devient indispensable d'ajouter l'en-tête Vary: Origin à la réponse. Sans cet en-tête, le cache peut mémoriser la réponse générée pour la première origine qui l'a demandée, puis la resservir telle quelle à une deuxième origine différente, ce qui provoque soit un blocage CORS (l'origine en cache ne correspond pas à l'appelant réel), soit, plus grave, une fuite de données vers une origine qui ne devrait pas y avoir accès si la réponse contient des données propres à l'utilisateur.

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Vary: Origin
Cache-Control: public, max-age=3600

C'est un bug qui ne se manifeste jamais en développement local (pas de cache intermédiaire) et qui apparaît uniquement en production, de façon intermittente selon l'ordre d'arrivée des requêtes sur un nœud de cache donné, ce qui en fait un des bugs CORS les plus difficiles à reproduire.

fetch et le mode no-cors : un piège silencieux côté client

Un dernier piège vient du client lui-même : appeler fetch(url, { mode: "no-cors" }) ne contourne pas CORS, contrairement à ce que le nom suggère. Ce mode autorise l'envoi de la requête sans vérification CORS, mais rend la réponse totalement opaque au JavaScript appelant : statut, headers et corps deviennent illisibles, même si la requête a techniquement réussi côté réseau. Un développeur qui ajoute ce mode pour "faire taire" l'erreur CORS dans la console obtient un code qui s'exécute sans erreur visible, mais qui ne peut plus jamais lire la donnée reçue, ce qui est souvent plus difficile à diagnostiquer qu'un blocage explicite.

À retenir : CORS protège l'utilisateur, pas le serveur, c'est pourquoi curl fonctionne quand le navigateur refuse. Toujours vérifier la requête OPTIONS et sa réponse brute avant de modifier la configuration, et ne jamais combiner un Access-Control-Allow-Origin: * avec des credentials.