Promise.prototype.catch()

Baseline Large disponibilité

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.

La méthode catch() renvoie un objet Promise et ne traite que des cas où la promesse initiale est rejetée. Elle a le même effet qu'un appel à Promise.prototype.then(undefined, siRejetée) (c'est en fait ce qui se passe dans le moteur, obj.catch(onRejected) est traduit en obj.then(undefined, onRejected)). Cela signifie qu'il est nécessaire de fournir une fonction onRejected, même si on souhaite avoir une valeur de secours qui est undefined (par exemple avec obj.catch(() => {}).

Dans cet article

Exemple interactif

const promise1 = new Promise((resolve, reject) => {
  throw new Error("Uh-oh!");
});

promise1.catch((error) => {
  console.error(error);
});
// Expected output: Error: Uh-oh!

Syntaxe

js
p.catch(siRejetée);

p.catch(function (raison) {
  // rejet
});

Paramètres

siRejetée

Une fonction à appeler si la Promise est rejetée (i.e. n'est pas tenue). Cette fonction possède un argument :

raison

Une chaîne de caractères qui indique pourquoi la promesse n'est pas tenue.

La promesse renvoyée par la méthode catch() est rompue si siRejetée lève une erreur ou si elle renvoie une promesse rompue. Dans les autres cas, elle est tenue.

Valeur de retour

Une promesse (Promise).

Description

La méthode catch() est utile pour gérer les cas d'erreur en cas de compositions de plusieurs promesses. Elle renvoie elle-même une promesse et peut donc être utilisée lorsqu'on chaîne des promesses, à l'instar de la méthode sœur qu'est Promise.prototype.then().

Exemples

Utilisation de la méthode catch

js
var p1 = new Promise(function (resolve, reject) {
  resolve("Succès");
});

p1.then(function (value) {
  console.log(value); // "Succès!"
  throw new Error("zut !");
})
  .catch(function (e) {
    console.error(e.message); // "zut !"
  })
  .then(function (e) {
    console.log("après le catch, la chaîne est restaurée");
  });

// Le code qui suit est équivalent :
p1.then(function (value) {
  console.log(value); // "Succès!"
  return Promise.reject("zut !");
})
  .catch(function (e) {
    console.log(e); // "zut !"
  })
  .then(function (e) {
    console.log("après le catch, la chaîne est restaurée");
  });

Les promesses n'interceptent pas les exceptions levées de façon asynchrone

js
var p1 = new Promise(function (resolve, reject) {
  throw new Error("Oh oh!");
});

p1.catch(function (e) {
  console.log(e.message); // "Oh oh!"
});

var p2 = new Promise(function (resolve, reject) {
  setTimeout(function () {
    throw new Error("Exception invisible !");
  }, 1000);
});

p2.catch(function (e) {
  console.log(e.message); // Cela n'est jamais appelé
});

Démonstration de l'appel interne à then

js
// On surcharge Promise.prototype.then/catch
// pour y ajouter des logs
(function (Promise) {
  var originalThen = Promise.prototype.then;
  var originalCatch = Promise.prototype.catch;

  Promise.prototype.then = function () {
    console.log(
      "> > > > > > appel de .then sur %o avec les arguments: %o",
      this,
      arguments,
    );
    return originalThen.apply(this, arguments);
  };
  Promise.prototype.catch = function () {
    console.log(
      "> > > > > > appel de .catch sur %o avec les arguments: %o",
      this,
      arguments,
    );
    return originalCatch.apply(this, arguments);
  };
})(this.Promise);

// On appelle catch sur une promesse déjà résolue
Promise.resolve().catch(function XXX() {});

// Dans la console, on aura :
// > > > > > > appel de .catch sur Promise{} avec les arguments: Arguments{1} [0: function XXX()]
// > > > > > > appel de .then sur Promise{} avec les arguments: Arguments{2} [0: undefined, 1: function XXX()]

Aider à améliorer MDN

Cette page vous a-t-elle été utile ?

Oui Non

Apprendre à contribuer

Cette page a été modifiée le 24 juin 2025 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu

Objets natifs standards
Promise
Constructeur
1. Constructeur Promise()
Méthodes statiques
Propriétés statiques
1. [Symbol.species]
Méthodes d'instance
Héritage
Object/Function
Méthodes statiques
Propriétés statiques
Méthodes d'instance
Propriétés d'instance
1. Object.prototype.__proto__
2. Object.prototype.constructor