Node.js: come gestire gli errori HTTP 500 e le eccezioni nel nostro codice

Scopri come gestire gli errori HTTP 500 in Node.js, intercettare eccezioni, creare middleware Express, proteggere le API e monitorare gli errori in produzione. 
Che cosa significa HTTP 500 Internal Server Error?
Il codice di stato HTTP 500, identificato come Internal Server Error, indica che il server ha incontrato una condizione inattesa che gli ha impedito di completare la richiesta. Si tratta di una risposta generica appartenente alla categoria degli errori server-side, ovvero ai codici HTTP compresi tra 500 e 599.
A differenza di un errore 400, che generalmente indica una richiesta non valida da parte del client, o di un 404, che segnala una risorsa non disponibile, un errore 500 comunica che il problema si è verificato durante l'elaborazione lato server.
Le cause possono essere differenti e non necessariamente riconducibili a un singolo componente. Tra le situazioni più comuni troviamo:
- eccezioni non gestite durante l'esecuzione del codice;
- errori nella logica applicativa o in un servizio interno;
- problemi di connessione a database o servizi esterni;
- configurazioni errate o variabili d'ambiente mancanti;
- risorse insufficienti, come memoria o connessioni disponibili;
- errori durante la serializzazione o la generazione della risposta;
- timeout non gestiti correttamente nelle operazioni asincrone.
Il codice 500 non descrive quindi la causa precisa del problema. È un'indicazione rivolta al client, mentre il dettaglio tecnico deve essere recuperato attraverso il sistema di logging, il monitoraggio e l'analisi del codice applicativo.
Quando restituire un errore 500
Non tutte le situazioni anomale devono essere gestite restituendo un HTTP 500. Una distinzione importante riguarda gli errori attesi, che fanno parte del normale flusso applicativo, e quelli inattesi, che indicano un problema durante l'esecuzione.
Se un utente richiede una risorsa inesistente, il server dovrebbe restituire un 404. Se i dati inviati non rispettano i requisiti di validazione, è più appropriato un 400 o, in contesti di API con validazione semantica, un 422.
Se invece l'applicazione tenta di eseguire un'operazione e incontra un errore imprevisto, come un'eccezione non prevista o una dipendenza interna che non risponde, il codice 500 può essere appropriato.
Un'altra distinzione importante riguarda il codice 503 Service Unavailable, che può essere utilizzato quando il servizio non è temporaneamente in grado di gestire le richieste, ad esempio durante manutenzione o in condizioni di sovraccarico.
La scelta del codice HTTP corretto permette al client di comprendere meglio il risultato della richiesta e ai sistemi intermedi, come proxy, load balancer o strumenti di monitoraggio, di adottare comportamenti appropriati.
Gestire gli errori in Node.js
Node.js utilizza diversi meccanismi per segnalare gli errori. In base al tipo di operazione, un errore può essere generato attraverso un'eccezione, una Promise rifiutata, un callback oppure un evento emesso da un oggetto.
Gli errori sincroni possono essere gestiti tramite
try...catch, mentre quelli asincroni richiedono
di considerare attentamente il meccanismo di propagazione utilizzato
dall'API.
Gestire un errore sincrono
try {
const result = executeOperation();
} catch (error) {
console.error('Errore durante l'operazione:', error);
}
Il blocco catch intercetta le eccezioni generate
all'interno del blocco try. Questo approccio è
appropriato quando puoi gestire l'errore localmente, ad esempio
recuperando da una condizione prevista o aggiungendo informazioni
utili prima di propagare l'errore.
Gestire un errore asincrono con async/await
Quando utilizzi funzioni asincrone, puoi intercettare le Promise
rifiutate tramite un blocco try...catch.
async function getUser(userId) {
try {
return await database.findUserById(userId);
} catch (error) {
console.error('Errore durante il recupero dell'utente:', error);
throw error;
}
}
In questo esempio, l'errore viene registrato e successivamente
rilanciato con throw. In questo modo il chiamante
può decidere come gestirlo, evitando che venga nascosto o trasformato
in un risultato apparentemente valido.
Intercettare un errore non significa necessariamente risolverlo. Se non puoi recuperare correttamente la situazione, è preferibile propagare l'errore al livello responsabile della gestione della richiesta.
Gestire gli errori HTTP 500 in un server Node.js nativo
Se utilizzi Node.js senza framework, puoi gestire direttamente
le richieste HTTP attraverso il modulo node:http.
In questo caso, la responsabilità di intercettare gli errori
e costruire la risposta ricade interamente sull'applicazione.
Un esempio di server che gestisce un errore durante l'elaborazione della richiesta:
import http from 'node:http';
const server = http.createServer(async (req, res) => {
try {
if (req.url === '/api/data') {
const data = await getData();
res.writeHead(200, {
'Content-Type': 'application/json'
});
res.end(JSON.stringify(data));
return;
}
res.writeHead(404, {
'Content-Type': 'application/json'
});
res.end(JSON.stringify({
error: 'Resource not found'
}));
} catch (error) {
console.error('Request error:', error);
if (res.headersSent) {
res.destroy(error);
return;
}
res.writeHead(500, {
'Content-Type': 'application/json'
});
res.end(JSON.stringify({
error: 'Internal Server Error'
}));
}
});
server.listen(3000);
Il blocco try...catch contiene il flusso di
elaborazione della richiesta. Se si verifica un errore durante
l'esecuzione di getData() o in un'altra operazione
asincrona attesa, il controllo passa al blocco catch.
Il server registra il dettaglio dell'errore e restituisce una risposta generica al client. Il messaggio inviato non contiene informazioni sullo stack, sul database, sulle directory interne o sulla configurazione dell'applicazione.
Il controllo su res.headersSent è altrettanto importante:
una volta che gli header o una parte del body sono stati inviati,
non è più possibile costruire una nuova risposta HTTP 500.
In questo caso, è necessario gestire la connessione in base
allo stato in cui si trova, evitando di tentare una seconda risposta.
Gestire gli errori 500 con Express
In molti progetti Node.js viene utilizzato Express per organizzare routing, middleware e gestione delle richieste. Il framework mette a disposizione un sistema di gestione degli errori che permette di centralizzare la logica di risposta.
Express distingue i normali middleware da quelli dedicati alla
gestione degli errori. Un error-handling middleware deve avere
quattro parametri: err, req,
res e next.
Creare un middleware per gli errori
app.use((err, req, res, next) => {
console.error(err);
if (res.headersSent) {
return next(err);
}
res.status(500).json({
error: 'Internal Server Error'
});
});
Il middleware deve essere registrato dopo le route e gli altri
middleware dell'applicazione, in modo da poter ricevere gli errori
che vengono propagati attraverso next(err).
La verifica di res.headersSent consente di delegare
la gestione al middleware predefinito di Express quando la risposta
è già stata avviata. Questo evita di tentare di inviare nuovi
header o un body su una risposta già in fase di trasmissione.
Il middleware può essere esteso per gestire logging, identificativi di richiesta, metriche e formati di risposta uniformi.
Propagare gli errori dalle route
Quando una route rileva un errore, può passarlo al sistema
centralizzato utilizzando next(error).
app.get('/api/users/:id', async (req, res, next) => {
try {
const user = await getUserById(req.params.id);
res.json(user);
} catch (error) {
next(error);
}
});
In questo modo la route non deve conoscere il formato della risposta di errore o le modalità di logging. Il middleware centralizzato si occupa di trasformare l'errore in una risposta HTTP.
La separazione delle responsabilità rende il codice più semplice da testare e consente di mantenere un comportamento coerente in tutti gli endpoint.
Centralizzare la gestione degli errori con una classe personalizzata
In un'applicazione strutturata può essere utile distinguere gli errori applicativi da quelli inattesi attraverso una classe personalizzata. Questo permette di associare all'errore informazioni come il codice HTTP, un messaggio destinato al client e un eventuale codice interno utile per il logging.
Una possibile implementazione:
export class AppError extends Error {
constructor(message, statusCode = 500, code = 'INTERNAL_ERROR') {
super(message);
this.name = 'AppError';
this.statusCode = statusCode;
this.code = code;
this.isOperational = true;
}
}
La proprietà isOperational può essere utilizzata
per distinguere gli errori previsti dalla logica applicativa
da quelli inattesi, come un bug o una condizione non contemplata.
Non è una proprietà standard di JavaScript: è una convenzione
che puoi adottare nel tuo progetto.
A questo punto puoi generare errori applicativi con informazioni precise:
throw new AppError(
'User not found',
404,
'USER_NOT_FOUND'
);
Oppure segnalare una condizione che richiede un errore server:
throw new AppError(
'Unable to complete the operation',
500,
'OPERATION_FAILED'
);
L'obiettivo non è rendere ogni errore personalizzato, ma fornire un modello uniforme per le condizioni che fanno parte del dominio applicativo e che devono essere comunicate in modo prevedibile.
Un error handler Express più completo
Dopo aver definito una classe per gli errori applicativi, puoi realizzare un middleware centralizzato che distingua gli errori previsti da quelli inattesi, registri i dettagli tecnici e restituisca al client un messaggio adeguato.
import { AppError } from './AppError.js';
app.use((err, req, res, next) => {
if (res.headersSent) {
return next(err);
}
const isOperational = err.isOperational === true;
const statusCode = isOperational
? err.statusCode
: 500;
const responseMessage = isOperational
? err.message
: 'Internal Server Error';
console.error({
message: err.message,
stack: err.stack,
method: req.method,
url: req.originalUrl
});
res.status(statusCode).json({
error: {
code: isOperational
? err.code
: 'INTERNAL_ERROR',
message: responseMessage
}
});
});
In questo esempio, gli errori riconosciuti come operativi mantengono il codice HTTP e il messaggio definiti dall'applicazione. Gli errori inattesi vengono invece trasformati in un generico 500, evitando di esporre al client dettagli interni.
Il logging include informazioni utili per identificare la richiesta che ha generato il problema. In un ambiente di produzione, è preferibile utilizzare un logger strutturato e associare a ogni richiesta un identificativo univoco, in modo da facilitare la correlazione tra log, metriche e trace.
Attenzione: non fidarti automaticamente di proprietà come
statusCode, isOperational o
message presenti su un errore arbitrario. In un
sistema reale, valida il tipo di errore e il range dello status
HTTP consentito, evitando che errori non attendibili producano
risposte improprie.
Errori asincroni e Promise non gestite
Una delle cause più frequenti di problemi in Node.js riguarda la gestione incompleta delle operazioni asincrone. Una Promise rifiutata non intercettata o un errore generato all'interno di una callback non collegata al flusso della richiesta possono non arrivare al middleware Express.
Considera questo esempio:
app.get('/api/report', (req, res) => {
generateReport()
.then(report => {
res.json(report);
});
});
Se generateReport() restituisce una Promise che viene
rifiutata, il codice non prevede un percorso per gestire il
rejection. Il risultato può essere una Promise non gestita e
l'applicazione non invierà necessariamente la risposta prevista.
Un approccio migliore consiste nell'utilizzare un handler asincrono e propagare gli errori al sistema di gestione:
app.get('/api/report', async (req, res, next) => {
try {
const report = await generateReport();
res.json(report);
} catch (error) {
next(error);
}
});
Con Express 5, gli errori e le Promise rifiutate dai route handler e middleware che restituiscono Promise vengono inoltrati automaticamente al sistema di gestione degli errori. Con Express 4, invece, devi intercettare e propagare esplicitamente gli errori asincroni, oppure utilizzare un wrapper dedicato.
È importante anche prestare attenzione alle callback e alle operazioni asincrone che non fanno parte della Promise restituita dalla route: timer, eventi o callback indipendenti devono gestire e propagare gli errori attraverso il meccanismo appropriato.
Logging: registrare gli errori senza esporli
Restituire un HTTP 500 è soltanto una parte della gestione dell'errore. Per individuare la causa reale del problema, devi registrare informazioni sufficienti a ricostruire il contesto in cui si è verificato.
Un log utile può contenere:
- messaggio e stack trace dell'errore;
- data e ora dell'evento;
- identificativo della richiesta;
- endpoint e metodo HTTP;
- identificativo dell'utente, se appropriato e senza esporre dati sensibili;
- servizio o componente che ha generato l'errore;
- eventuali informazioni sul contesto operativo.
Per esempio, puoi utilizzare un logger strutturato:
logger.error({
err: error,
requestId: req.id,
method: req.method,
path: req.originalUrl
}, 'Unexpected server error');
Strumenti come Pino o Winston permettono di produrre log strutturati, semplificando la ricerca e l'analisi degli errori attraverso sistemi centralizzati.
Evita di registrare indiscriminatamente token, password, cookie, dati personali o payload che potrebbero contenere informazioni sensibili. Il logging deve essere progettato in modo da aiutare il debugging senza creare un ulteriore rischio di sicurezza.
Non esporre dettagli interni al client
Quando si verifica un errore 500, è importante non restituire direttamente al client l'oggetto Error, il suo stack trace o messaggi provenienti da database e servizi interni.
Informazioni come nomi di file, percorsi, query, configurazioni, nomi di servizi o stack trace potrebbero aiutare un potenziale attaccante a comprendere meglio l'architettura dell'applicazione.
Una risposta API dovrebbe mantenere un formato prevedibile e contenere soltanto le informazioni necessarie:
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred."
}
}
Il dettaglio tecnico rimane nei log server-side, mentre il client riceve un messaggio generico e, se necessario, un identificativo che consenta al supporto tecnico di risalire all'evento.
Questa separazione è fondamentale per realizzare API sicure e mantenere un controllo effettivo sulle informazioni esposte.
Gli errori 500 e la stabilità del processo Node.js
Un errore HTTP 500 riguarda una singola richiesta, ma non tutti gli errori sono limitati al contesto di una richiesta. Alcune eccezioni possono raggiungere il processo Node.js senza essere intercettate, compromettendo lo stato dell'applicazione.
È importante distinguere gli errori gestibili a livello di richiesta da quelli che indicano uno stato potenzialmente inconsistente del processo.
L'evento uncaughtException può essere utilizzato
come ultima risorsa per registrare un'eccezione non intercettata,
ma non dovrebbe diventare un sistema generico per evitare
la terminazione del processo.
process.on('uncaughtException', (error, origin) => {
logger.fatal({
err: error,
origin
}, 'Uncaught exception');
process.exitCode = 1;
});
L'esempio mostra come registrare un'eccezione non intercettata, ma in produzione non è sufficiente impostare l'exit code e lasciare il processo in esecuzione.
Dopo un'eccezione non intercettata, lo stato del processo potrebbe non essere più affidabile. Una strategia più sicura consiste nel terminare il processo e affidare il riavvio a un process manager o a un sistema di orchestrazione, come systemd, PM2 o Kubernetes, dopo aver eseguito le operazioni di cleanup compatibili con lo stato del processo.
In alternativa, l'evento uncaughtExceptionMonitor
consente di osservare l'eccezione senza modificare il comportamento
predefinito di Node.js, che prevede la terminazione del processo.
Non utilizzare uncaughtException come sostituto
del normale sistema di error handling: gli errori devono essere
gestiti nei contesti in cui possono essere recuperati in modo sicuro.
Monitoraggio e prevenzione degli errori 500
Una gestione efficace degli errori server-side non si limita all'intercettazione delle eccezioni. In un'applicazione reale, è necessario monitorare la frequenza degli errori, individuare eventuali anomalie e comprendere se un aumento dei 500 è associato a un deploy, a un servizio esterno o a un problema infrastrutturale.
Alcune pratiche utili includono:
- monitorare la percentuale di risposte HTTP 5xx;
- configurare alert in caso di aumento significativo degli errori;
- utilizzare logging strutturato e request ID;
- tracciare le dipendenze esterne e i tempi di risposta;
- implementare timeout e limiti per operazioni esterne;
- utilizzare retry solo quando appropriati, evitando di amplificare il carico;
- verificare la disponibilità dei servizi essenziali;
- testare scenari di errore attraverso test automatici.
Sistemi di observability come OpenTelemetry, insieme a strumenti di monitoraggio e raccolta log, possono aiutarti a individuare più rapidamente le cause dei problemi e a ridurre il tempo necessario per ripristinare il servizio.
L'obiettivo non è eliminare completamente gli errori, un risultato irrealistico in sistemi complessi, ma fare in modo che siano identificabili, circoscritti e gestiti con il minor impatto possibile sugli utenti.
Conclusioni
Gestire correttamente gli errori HTTP 500 in Node.js significa progettare un sistema che sappia distinguere gli errori previsti da quelli inattesi, intercettare le eccezioni nei contesti appropriati e restituire al client risposte coerenti e sicure.
La centralizzazione della gestione degli errori, l'utilizzo di middleware dedicati, la propagazione corretta delle Promise rifiutate e un sistema di logging strutturato sono elementi fondamentali per mantenere un backend affidabile e manutenibile.
È altrettanto importante non confondere la gestione di un errore HTTP con la gestione di un errore fatale del processo. Un 500 può essere risolto a livello di richiesta, mentre un'eccezione non intercettata può richiedere la terminazione e il riavvio del servizio.
Un sistema di error handling ben progettato non serve soltanto a rispondere a un problema: serve a proteggere il servizio, facilitare la diagnosi e ridurre l'impatto degli imprevisti sull'esperienza degli utenti.
Link utili
- Node.js Documentation - Errors : documentazione ufficiale sulle tipologie di errore e sui meccanismi di propagazione e intercettazione.
-
Node.js Documentation - Process
: approfondimento sugli eventi del processo, inclusi
uncaughtExceptioneuncaughtExceptionMonitor. - Express - Error Handling : guida ufficiale alla gestione degli errori nelle route e nei middleware.
- Express - Production Best Practices : indicazioni su stabilità, performance e gestione degli errori in ambiente di produzione.
- MDN - HTTP 500 Internal Server Error : descrizione del codice di stato HTTP 500 e del suo significato.
- OpenTelemetry - JavaScript : strumenti e risorse per l'observability delle applicazioni JavaScript e Node.js.
