Promise.prototype.catch()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

O método catch() retorna uma Promise e lida apenas com casos rejeitados. Ele possui o mesmo comportamento de quando chamamos Promise.prototype.then(undefined, onRejected) (de fato, chamando obj.catch(onRejected) internamente é chamado obj.then(undefined, onRejected)).

Sintaxe

p.catch(onRejected); p.catch(function(motivo) { // rejeição });

Parâmetros

onRejected

Uma Function chamada quando a Promise é rejeitada. Esta função possui um argumento: reason da rejeição. O motivo da rejeição.

A Promise retornada pelo catch() é rejeitada apenas se onRejected cospe um erro ou se o o retorno da Promise foi rejeitada por si mesmo, ou seja, foi resolvida.

Valor de retorno

Internamente chamamos Promise.prototype.then sobre o objeto que é chamando passando parâmetros como undefined e onRejected no manipulador de eventos. Então retornamos o valor da chamada que é Promise.

Aviso: O exemplo abaixo está cuspindo uma string. Isso é considerado uma má prática. Sempre cuspir uma instance de erro (Error). Em todo caso, a parte que faz a captura deve fazer verificaçoes sobre os argumentos para saber se é uma string ou um erro e você poderá perder informações valiosas como stack traces.

Demonstração de uma camada interna:

js
// Sobrescrevendo o techo original de Promise.prototype.then/catch adicionando alguns logs (function (Promise) { var originalThen = Promise.prototype.then; var originalCatch = Promise.prototype.catch; Promise.prototype.then = function () { console.log( "> > > > > > chamando .then em %o com argumentos: %o", this, arguments, ); return originalThen.apply(this, arguments); }; Promise.prototype.catch = function () { console.log( "> > > > > > chamando .catch em %o com argumentos: %o", this, arguments, ); return originalCatch.apply(this, arguments); }; })(this.Promise); // chamando um catch em uma Promise já resolvida. Promise.resolve().catch(function XXX() {}); // logs: // > > > > > > chamando .catch na Promise{} com os argumentos: Arguments{1} [0: function XXX()] // > > > > > > chamando .then na Promise{} com os argumentos: Arguments{2} [0: undefined, 1: function XXX()]

Description

O método catch pode ser útil para manipulação de erros na composição da sua promise.

Exemplos

Usando o método catch

js
var p1 = new Promise(function (resolve, reject) { resolve("Sucesso"); }); p1.then(function (value) { console.log(value); // "Sucesso!" throw "Ah, não!"; }) .catch(function (e) { console.log(e); // "Ah, não!" }) .then( function () { console.log("Após um catch, a sequencia é restaurada"); }, function () { console.log("Não engatilhado devido ao catch"); }, ); // O seguinte se comporta da mesma maneira que o anterior p1.then(function (value) { console.log(value); // "Sucesso!" return Promise.reject("Ah, não!"); }) .catch(function (e) { console.log(e); // "Ah, não!" }) .then( function () { console.log("Após um catch, a sequencia é restaurada"); }, function () { console.log("Não engatilhado devido ao catch"); }, );

Especificações

Specification
ECMAScript® 2026 Language Specification
# sec-promise.prototype.catch

Compatibilidade com navegadores

Veja também