handleServerError

Transforme n’importe quelle erreur en réponse JSON standardisée pour les API Next.js. Centralise la gestion d’erreurs dans un seul point de sortie et garantit un format uniforme { message, code, status }.

Sécurité : En production (NODE_ENV=production), les erreurs non explicites (HttpError) renvoient un message générique «Erreur serveur»pour éviter de fuiter des détails sensibles (SQL, stack trace, etc.). En développement, le message détaillé est préservé pour le debug.

Utilisation de base — Try / Catch dans une route API

Dans un handler de route Next.js, entourer la logique métier d’un try/catch et déléguer à handleServerError.

import { handleServerError, HttpError } from "@ramses1er/cbk-toolkit/server";

export async function GET() {
  try {
    const user = await findUserById(id);

    if (!user) {
      throw new HttpError("Utilisateur introuvable", 404, "USER_NOT_FOUND");
    }

    return Response.json(user, { status: 200 });
  } catch (error) {
    return handleServerError(error);
  }
}

Résultat de handleServerError(error) :

HttpError → utilise son .message, .code et .status (toujours visible)
Errornatif → message détaillé en dev, générique en prod
Objet brut → sérialisé en JSON en dev, générique en prod
String / autre → converti via String()en dev, générique en prod

Avec status par défaut personnalisé

Le second paramètre defaultStatus permet de surcharger le code HTTP par défaut (500) pour les erreurs qui ne sont pas des HttpError.

import { handleServerError } from "@ramses1er/cbk-toolkit/server";

try {
  await processData(payload);
} catch (error) {
  // Toute erreur non-HttpError renverra un 400 au lieu de 500
  return handleServerError(error, 400);
}

Sécurité — Mode production

Le troisième paramètre showDetailspermet de contrôler manuellement l’affichage des détails :

undefined (défaut) → automatique selon NODE_ENV
true→ force les détails (utile pour debug en prod temporaire)
false→ force le mode sécurisé (message générique)

import { handleServerError } from "@ramses1er/cbk-toolkit/server";

try {
  await processData(payload);
} catch (error) {
  // Mode automatique : détail en dev, générique en prod
  return handleServerError(error);

  // Forcer les détails (override NODE_ENV)
  return handleServerError(error, 500, true);

  // Forcer le mode sécurisé
  return handleServerError(error, 500, false);
}

Rappel : Les HttpErrorsont toujours visibles en détail, quel que soit le mode. La sécurisation ne concerne que les erreurs non explicites (SQL, erreurs inattendues, etc.).

Pattern recommandé — Wrapper réutilisable

Au lieu de répéter le try/catch dans chaque route, on crée un wrapper qui intercepte les erreurs automatiquement.

import { handleServerError } from "@ramses1er/cbk-toolkit/server";

type Handler = (req: Request) => Promise<Response>;

function withHandler(handler: Handler): Handler {
  return async (req) => {
    try {
      return await handler(req);
    } catch (error) {
      return handleServerError(error);
    }
  };
}

// Utilisation
export const GET = withHandler(async (req) => {
  const users = await getUsers();
  return Response.json(users);
});

export const POST = withHandler(async (req) => {
  const body = await req.json();
  const user = await createUser(body);
  return Response.json(user, { status: 201 });
});

API de référence

Propriété	Type	Défaut	Description
`handleServerError(error, defaultStatus?, showDetails?)`
error	unknown	requis	L’erreur capturée (HttpError, Error, objet, string...)
defaultStatus	number	500	Code HTTP par défaut si l’erreur n’a pas de status
showDetails	boolean \| undefined	`NODE_ENV !== "production"`	Force les détails (true) ou le mode sécurisé (false). Auto par défaut
Réponse JSON `{ message, code, status }`
message	string	—	Message d’erreur
code	string	INTERNAL_ERROR	Code d’erreur
status	number	500	Code HTTP retourné