Tratamento de erros em Promises e async/await

Objetivo

Toda promise rejeitada é tratada no ponto em que dá para fazer algo útil ou aparece como uma falha registrada em log, com contexto. Nenhuma é descartada em silêncio e nenhuma derruba o processo de surpresa.

Pré-requisitos

Uma função async sempre retorna uma promise: um throw dentro dela vira uma rejeição, e await sobre uma promise rejeitada relança o erro naquele ponto (MDN). Conheça a política do runtime para rejeições que ninguém trata: os navegadores disparam um evento unhandledrejection em window; o Node.js, com o padrão --unhandled-rejections=throw, a trata como exceção não capturada, o que encerra o processo, a menos que seja tratada.

Passos

1. Para cada chamada com await, decida se quem chama consegue se recuperar (tentar de novo, usar uma alternativa, mostrar uma mensagem). Só então envolva a chamada: try { data = await load(); } catch (e) { ... } apenas em volta das instruções que podem falhar, não da função inteira.
2. Quando não houver como se recuperar, deixe a rejeição se propagar ou relance um erro mais específico que mantenha o original anexado (new Error("profile load failed", { cause: e })), para que a stack trace não se perca.
3. Nunca deixe uma promise solta. Uma chamada sem await, return ou .catch é uma rejeição sem dono; ative uma regra de lint que sinalize promises sem await e corrija cada ocorrência.
4. Não misture cadeias de .then() e await na mesma função; a falta de um return dentro de .then esconde a falha do try externo.
5. Em trabalho concorrente, escolha com critério: Promise.all quando uma única falha invalida o lote, Promise.allSettled quando resultados parciais são úteis. Em ambos os casos, toda promise de entrada recebe um handler, de modo que falhas posteriores não se tornam rejeições não tratadas.
6. Registre um handler de último recurso que grave em log o motivo e a origem da promise: window.addEventListener("unhandledrejection", ...) no navegador, process.on("unhandledRejection", ...) no Node.js. Em um processo de servidor, registre e encerre, em vez de continuar com um estado desconhecido.
7. Rejeite sempre com instâncias de Error; uma string rejeitada não tem stack trace nem cause.
8. Escreva um teste para cada caminho de falha documentado, verificando o tipo e a mensagem da rejeição.

Resultado esperado

As falhas aparecem uma só vez, em uma linha de log com contexto, na camada que decidiu o que fazer com elas. As execuções de CI não mostram avisos de rejeição não tratada.

Limites e base de verificação

Cancelamento não é uma condição de erro; um AbortError de um fetch cancelado deve ser reconhecido e ignorado, não reportado. O comportamento descrito segue a documentação citada; nenhuma medição é alegada.