Failed to fetch - Démystifiez l'erreur réseau en JavaScript

Dans le frontend, certains messages d’erreur sont trompeurs, et celui-ci en fait partie. L’erreur générique failed to fetch apparaît quand le navigateur n’arrive pas au bout d’une requête réseau, mais la vraie cause peut venir du CORS, d’un mélange HTTP/HTTPS, d’un DNS, d’un certificat, d’une extension ou d’un service worker. Ici, je détaille comment la lire correctement, la diagnostiquer sans perdre de temps et la corriger proprement dans une application JavaScript.

Ce que ce message signifie réellement dans le navigateur

Je commence toujours par distinguer deux familles de problèmes. D’un côté, il y a les réponses HTTP valides mais négatives, comme un 404 ou un 500. De l’autre, il y a les échecs de transport, quand la requête n’aboutit pas vraiment. Selon MDN, fetch() ne rejette pas une promesse parce que le serveur répond avec un code d’erreur HTTP ; il rejette surtout en cas de mauvaise URL ou de panne réseau.

Autrement dit, si votre code voit un rejet, le navigateur n’a pas obtenu de réponse exploitable. Il peut s’agir d’un blocage avant même l’envoi, d’une connexion interrompue, d’un problème TLS, d’un CORS mal configuré ou d’une réponse empêchée par le contexte de sécurité. C’est précisément pour cela que ce message est si frustrant : il est générique par design, pas parce que le navigateur “ne sait pas”.

Dans la pratique, je lis ce type d’erreur comme un signal de diagnostic, pas comme une information finale. La vraie question devient alors : à quel endroit la chaîne s’est-elle cassée ? Une fois cette distinction posée, on peut passer aux causes les plus fréquentes.

Les causes les plus courantes à vérifier en premier

Quand je dois trier une alerte de réseau côté frontend, je regarde d’abord les causes qui reviennent le plus souvent. Elles ne demandent pas toutes la même correction, et les traiter dans le mauvais ordre fait perdre du temps. Voici le tableau mental que j’utilise.

Cette première passe suffit souvent à réduire le champ des possibles à deux ou trois pistes. Je passe alors au navigateur lui-même, parce que c’est là que les indices les plus utiles apparaissent.

Comment isoler le problème dans DevTools

Quand je veux savoir si le souci vient du frontend, du réseau ou du serveur, j’ouvre l’onglet Network avant de modifier le code. C’est la méthode la plus directe, parce qu’elle montre si la requête a été envoyée, bloquée, annulée ou rejetée avant toute réponse HTTP.

1. Je reproduis l’action fautive avec Network ouvert et je vérifie si la requête apparaît.
2. Si elle n’apparaît pas, je regarde la console, les extensions et les règles de sécurité du site.
3. Si elle apparaît sans réponse utile, je lis les headers, le statut, le CORS et l’eventuel preflight OPTIONS.
4. Si le navigateur affiche un statut 0 ou rien de lisible, je teste la même URL hors de l’application pour séparer le problème du code React, Vue ou Angular.
5. Si le problème ne survient que dans une configuration précise, je compare l’environnement local, la préproduction et la production.

J’insiste sur un point souvent mal interprété : le panneau Console ne suffit pas. Il résume l’échec, mais il ne raconte pas le trajet complet. Dans beaucoup de cas, l’onglet Network montre si la requête a été bloquée par une politique de sécurité avant même d’atteindre votre backend.

Le navigateur donne donc les indices, mais il faut encore écrire du code qui les traite correctement. C’est là que les bonnes pratiques de fetch() font une vraie différence.

Le bon modèle de code pour ne pas masquer l’erreur

La correction la plus fréquente que je fais dans les projets frontend, c’est de séparer nettement trois cas : la réponse HTTP en erreur, l’échec réseau et l’annulation volontaire. Beaucoup d’équipes mélangent tout dans un seul catch, puis s’étonnent de ne pas pouvoir distinguer un 404 d’une requête coupée.

async function requestJson(url, options = {}) {
  const signal = options.signal ?? AbortSignal.timeout(8000);

  try {
    const response = await fetch(url, { ...options, signal });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    if (error.name === 'TimeoutError') {
      throw new Error('La requête a dépassé le délai autorisé.');
    }

    if (error.name === 'AbortError') {
      throw new Error('La requête a été annulée.');
    }

    throw new Error('La requête réseau a échoué.');
  }
}

Ce pattern fonctionne bien pour trois raisons. D’abord, il ne confond pas un statut HTTP défavorable avec une panne réseau. Ensuite, il pose un timeout explicite au lieu de laisser l’interface tourner indéfiniment. Enfin, il rend le comportement de l’application lisible pour le reste du code, ce qui simplifie les messages d’erreur et la télémétrie.

Je nuance toutefois un point : je ne recommande pas de retenter automatiquement toutes les requêtes. Une reprise silencieuse peut être utile sur un GET idempotent, mais elle est mauvaise sur un POST sensible, un paiement ou une opération qui peut produire des doublons. Le retry doit être volontaire, borné et réservé aux cas où il a une vraie valeur.

Une fois le code assaini, il reste les causes qui échappent complètement au frontend. C’est là que la configuration serveur devient le sujet principal.

Quand la correction doit se faire côté serveur ou proxy

Si la cause est du côté backend, le frontend ne peut pas “réparer” l’erreur, seulement l’exposer plus clairement. C’est particulièrement vrai pour le CORS, le HTTPS et les proxys de déploiement. Dans ces cas-là, la solution durable se joue dans l’infrastructure.

• CORS : l’API doit autoriser explicitement l’origine du site, les méthodes utilisées et les en-têtes nécessaires.
• Preflight : la réponse OPTIONS doit être cohérente avec la vraie requête, sinon le navigateur coupe avant l’appel principal.
• HTTPS : si la page est servie en HTTPS, évitez d’appeler une API en HTTP, sinon le navigateur peut bloquer la requête pour contenu mixte.
• Certificats : un certificat expiré, auto-signé ou mal chaîné suffit à faire échouer la connexion.
• Proxy de développement : en local, un proxy évite souvent les faux positifs CORS, mais il ne remplace pas une configuration serveur correcte.
• Cookies et credentials : si vous envoyez des identifiants, alignez credentials, SameSite et les en-têtes CORS associés.

Je vois encore trop souvent des équipes ajouter des contournements côté frontend alors que le problème vient d’une règle d’origine croisée ou d’un reverse proxy mal configuré. C’est court-termiste. Le navigateur applique des règles de sécurité précises, et il vaut mieux les satisfaire que les contourner.

Quand ces réglages sont posés, il reste une dernière étape : éviter que le problème revienne sans être vu en production.

Ce que je mets en place pour que le problème ne revienne pas

La meilleure correction n’est pas seulement technique, elle est aussi opérationnelle. Je préfère un frontend qui signale clairement l’échec, journalise le contexte utile et propose une sortie propre plutôt qu’une interface qui se contente d’un message vague et d’un écran figé.

• Je distingue dans le code les erreurs réseau, les erreurs HTTP et les annulations.
• Je logue l’URL, la méthode, le temps d’attente et le type d’échec, sans stocker de données sensibles.
• Je prévois un état d’interface explicite pour l’absence de réseau, plutôt qu’un simple loader infini.
• Je n’utilise la reprise automatique que sur des requêtes sûres et avec une stratégie de backoff raisonnable.
• Je teste régulièrement le parcours en navigation privée, avec des extensions désactivées et sur un réseau plus restrictif.
• Je traite navigator.onLine comme un indice d’UX, pas comme une preuve absolue de connectivité.

Au fond, ce type d’erreur est moins un bug isolé qu’un test de maturité frontend. Une application robuste ne suppose pas que le réseau est parfait ; elle sait différencier les cas, signaler le bon niveau de panne et éviter les faux diagnostics. C’est cette discipline qui transforme un message opaque en information exploitable, puis en correction durable.