Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Promise.reject — criar uma promise rejeitada

Promise.reject(reason) cria uma nova promise rejeitada com o motivo indicado. Os handlers de rejeição são executados de forma assíncrona, embora a promise devolvida já esteja rejeitada quando é devolvida.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

Promise.reject(reason)

Promise.reject(reason) é um método estático do construtor Promise. Devolve uma nova promise no estado rejeitado, tendo reason como motivo da rejeição. O motivo pode ser qualquer valor; se o argumento for omitido, é usado undefined. Para erros, prefira um objeto Error.

O método não adota o estado de uma promise fornecida nem o de um objeto com um método then (um thenable). Esse argumento passa a ser o próprio motivo da rejeição. Ao contrário de Promise.resolve, Promise.reject não devolve uma promise fornecida sem alterações.

Uma chamada normal a Promise.reject(reason) não é um throw síncrono: um try...catch à sua volta não captura a rejeição em si. Use .catch(...) ou um try...catch em torno de await. Os handlers de promise só são executados depois de terminar o código síncrono atual. Trate as rejeições; a resposta a uma rejeição não tratada depende do ambiente anfitrião.

No exemplo, sync aparece antes de o handler de rejeição ser executado, e true confirma que o motivo mantém a sua identidade. Chame o método como Promise.reject(...): o seu this tem de ser um construtor compatível com as convenções do construtor Promise, pelo que uma chamada desligada sem o recetor correto pode lançar um TypeError.

Exemplos

const reason = new Error("Invalid input");
const rejected = Promise.reject(reason);

rejected.catch((error) => {
  console.log(error === reason);
  console.log(error.message);
});

console.log("sync");

Resultado

sync
true
Invalid input

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes