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

CKTIS / JavaScript

PromiseRejectionEvent.reason — motivo de rejeição de uma promessa

PromiseRejectionEvent.reason expõe o motivo de rejeição nos eventos unhandledrejection e rejectionhandled. A propriedade é só de leitura, mas o seu valor pode ser qualquer valor JavaScript, não apenas um objeto Error.

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

event.reason
new PromiseRejectionEvent(type, { promise, reason })

PromiseRejectionEvent é uma interface de Web API que herda de Event e não faz parte do próprio ECMAScript. A propriedade PromiseRejectionEvent.reason, lida como event.reason, contém o motivo de rejeição. Pode ser uma cadeia de caracteres, um número, um Error, outro objeto ou undefined; por isso, não pressuponhas que event.reason.message existe.

reason é só de leitura. Em contrapartida, event.promise identifica a promessa associada ao evento: estas propriedades representam, respetivamente, o motivo e a promessa, e não duas formas de ler o mesmo elemento.

unhandledrejection assinala uma rejeição sem um manipulador disponível. rejectionhandled significa que foi adicionado um manipulador mais tarde, depois de unhandledrejection já ter sido assinalado. Os listeners globais ajudam no diagnóstico, mas não substituem o tratamento de erros com .catch() ou try/catch à volta de await.

O exemplo cria manualmente um evento para demonstrar o acesso à propriedade de forma determinística. O argumento reason do construtor define o valor neste evento sintético; criar o evento não rejeita uma promessa nem o despacha. O .catch() imediato evita uma rejeição real não tratada.

Executa o exemplo num navegador que disponibilize PromiseRejectionEvent. Esta API também está disponível em Web Workers; a presença de Promise ou a utilização do Node 24 não comprova o suporte desta interface do navegador.

Exemplos

(() => {
  const reason = "TASK_FAILED";
  const promise = Promise.reject(reason);
  promise.catch(() => {});

  const event = new PromiseRejectionEvent("unhandledrejection", {
    promise,
    reason,
  });

  console.log(event.reason);
  console.log(event.promise === promise);
})();

Resultado

TASK_FAILED
true

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