Patterns de gestion d'erreurs avec Claude Code: classer les echecs aux frontieres

La gestion d’erreurs ne consiste pas a ajouter des try-catch partout. Quand on demande simplement a Claude Code de “corriger cette erreur”, le correctif risque de rester flou: toutes les situations deviennent des 500, les logs ne disent pas qui peut agir, et les erreurs de validation se melangent avec les pannes d’un fournisseur externe.

Le pattern utile est simple: classer l’echec a la frontiere et rendre le chemin de reprise explicite. Une frontiere est le point ou votre application touche quelque chose que vous ne controlez pas totalement: corps de requete API, fournisseur de paiement, CRM, service email, job planifie, import CSV ou interface utilisateur. Quand cette frontiere est nommee, Claude Code peut appliquer des regles concretes: une entree invalide renvoie 400, une API temporairement indisponible peut etre retentee, un batch echoue laisse une trace rejouable.

Cet article presente une approche accessible aux debutants, mais utile en production. Vous y trouverez un exemple TypeScript copiable, trois cas d’usage, les pieges courants, un prompt de revue pour Claude Code, des liens officiels et une piste de monetisation via formation ou ressources.

Penser reprise avant nommage

La premiere question n’est pas le nom de la classe. La premiere question est: que doit faire le systeme apres l’echec ?

Frontiere	Exemple	Reponse	Reprise
Validation API	Email invalide, nombre hors limite, JSON incorrect	400	L’utilisateur corrige la saisie
API externe	Paiement, CRM, email ou analytics indisponible	502 ou 503	Reessayer, suspendre, signaler un echec temporaire
Job/Batch	Rapport nocturne, import CSV, notifications	Trace interne	Rejeu sur, file d’echecs, alerte

Un simple message est trop fragile. Il parle aux humains, mais il ne permet pas de piloter le code. Ajoutez des champs lisibles par la machine comme kind, code, retryable et status. Claude Code peut alors verifier un comportement, pas seulement une phrase.

Exemple TypeScript executable

L’exemple suivant fonctionne avec Node.js 18 ou plus. Il utilise tsx pour executer TypeScript et n’appelle aucune vraie API externe. Le fetcher est injecte afin de rendre le cas d’erreur reproductible.

npm install -D tsx typescript
npx tsx error-patterns-demo.ts

type Kind = "validation" | "external" | "job";
type AppError = { kind: Kind; code: string; message: string; retryable: boolean; status: number; detail?: unknown };
type Result<T> = { ok: true; value: T } | { ok: false; error: AppError };

const ok = <T>(value: T): Result<T> => ({ ok: true, value });
const fail = <T>(error: AppError): Result<T> => ({ ok: false, error });

function parseUser(body: unknown): Result<{ email: string; age: number }> {
  if (typeof body !== "object" || body === null) {
    return fail({ kind: "validation", code: "BODY_REQUIRED", message: "body must be an object", retryable: false, status: 400 });
  }
  const data = body as Record<string, unknown>;
  if (typeof data.email !== "string" || !data.email.includes("@")) {
    return fail({ kind: "validation", code: "EMAIL_INVALID", message: "email is invalid", retryable: false, status: 400 });
  }
  if (typeof data.age !== "number" || data.age < 13) {
    return fail({ kind: "validation", code: "AGE_INVALID", message: "age must be 13 or greater", retryable: false, status: 400 });
  }
  return ok({ email: data.email, age: data.age });
}

async function callPartner(fetcher: () => Promise<Response>): Promise<Result<{ id: string }>> {
  try {
    const response = await fetcher();
    if (!response.ok) {
      return fail({ kind: "external", code: "PARTNER_HTTP", message: `partner returned ${response.status}`, retryable: response.status >= 500, status: 503 });
    }
    const json = (await response.json()) as { id?: unknown };
    if (typeof json.id !== "string") {
      return fail({ kind: "external", code: "PARTNER_PAYLOAD", message: "partner payload is invalid", retryable: false, status: 502, detail: json });
    }
    return ok({ id: json.id });
  } catch (error) {
    return fail({ kind: "external", code: "PARTNER_UNREACHABLE", message: "partner is unreachable", retryable: true, status: 503, detail: error });
  }
}

async function runJob<T>(name: string, work: () => Promise<T>, retries = 2): Promise<Result<T>> {
  for (let attempt = 1; attempt <= retries + 1; attempt += 1) {
    try {
      return ok(await work());
    } catch (error) {
      if (attempt <= retries) continue;
      return fail({ kind: "job", code: "JOB_FAILED", message: `${name} failed`, retryable: true, status: 500, detail: { attempt, error } });
    }
  }
  return fail({ kind: "job", code: "JOB_FAILED", message: `${name} failed`, retryable: true, status: 500 });
}

console.log(parseUser({ email: "bad", age: 10 }));
console.log(await callPartner(async () => new Response("down", { status: 503 })));
console.log(await runJob("daily-report", async () => ({ exportedRows: 42 })));

Cas 1: validation d’entree API

Une erreur de validation est souvent corrigeable par l’utilisateur. Email invalide, age trop bas, JSON qui n’est pas un objet ou plan inconnu ne devraient pas ressembler a une panne serveur. Dans l’exemple, parseUser classe le probleme en validation, renvoie 400 et fixe retryable: false.

Cette precision aide le frontend, le support et Claude Code. L’interface peut afficher le champ fautif, les logs peuvent etre filtres par EMAIL_INVALID, et les tests peuvent couvrir des chemins d’echec clairs. Pour aller plus loin, reliez ce pattern a l’automatisation des tests API avec Claude Code et aux strategies de test Claude Code.

Cas 2: echec d’API externe

Un service externe peut echouer meme si votre code est correct. Paiement, email, CRM, tableur ou analytics peuvent produire timeouts, limites de debit ou payloads inattendus. La separation essentielle est entre ce qui merite un retry et ce qui demande une correction de contrat.

Dans l’exemple, un 5xx devient retryable: true, alors qu’un payload mal forme devient retryable: false. Retenter un payload incorrect ne fait qu’ajouter du bruit dans les files et les logs. Pour verifier la semantique de response.ok, consultez MDN Response.ok. Si votre API utilise Express, la documentation Express error handling est la reference a garder sous la main.

Cas 3: echec de job ou batch

Les jobs echouent souvent loin de l’ecran utilisateur. Rapport nocturne, import CSV, generation de facture ou envoi de notifications doivent donc laisser des informations rejouables. runJob garde le nom du job, le nombre final de tentatives et la possibilite de reessayer. En production, ces donnees doivent aller dans des logs structures, une file de dead-letter, une interface admin ou une alerte.

Le mot important est idempotence. Une operation idempotente peut etre relancee sans doubler les effets. Si un import CSV cree des lignes en double ou si un job de facturation debite deux fois, le retry n’est plus une protection. Demandez a Claude Code de verifier la reprise, pas seulement le typage.

Pieges frequents

Premier piege: catch { return null; }. Cela efface les preuves necessaires au diagnostic. Deuxieme piege: exposer a l’utilisateur une stack trace, un nom SQL, une variable d’environnement ou un fragment de token. Pour l’angle securite, consultez l’audit securite avec Claude Code. Troisieme piege: tout reessayer. Une erreur de validation ou un payload impossible ne se corrige pas avec le temps.

Quatrieme piege: creer de beaux types sans regle d’equipe. Les unions discriminantes et le narrowing de TypeScript sont puissants, mais quelqu’un peut reintroduire throw new Error("failed") demain. Appuyez-vous sur TypeScript Narrowing, puis ecrivez la regle dans AGENTS.md ou CLAUDE.md.

Prompt de revue Claude Code

Revois la gestion d'erreurs de cette PR.
Points a verifier:
1. Les echecs sont classes aux frontieres API, API externe et job/batch.
2. Les erreurs corrigeables par l'utilisateur ne deviennent pas des 500.
3. retryable et non-retryable sont separes.
4. La reponse n'expose ni stack trace, ni SQL, ni secret, ni chemin interne.
5. Les logs conservent code, kind, attempt et cause sure.
6. Au moins 3 chemins d'echec sont testes.
Propose le plus petit patch sur et les tests associes.

Pour verrouiller ces chemins, le Node.js test runner suffit souvent. Les reglages et la memoire de projet Claude Code se verifient depuis Claude Code overview. Si vous voulez demarrer par les tests, poursuivez avec TDD avec Claude Code et techniques de debug Claude Code.

CTA et resultat teste par Masa

La gestion d’erreurs est un excellent sujet de formation: elle relie API, logs, securite, tests et operations. Pour commencer seul, telechargez la cheat sheet gratuite. Pour des prompts, checklists et templates prets pour une equipe, consultez la bibliotheque de produits. Pour remettre a niveau un depot existant, la page formation et conseil Claude Code permet de passer en revue API, integrations externes et batchs.

Dans le workflow de Masa, rapprocher validation, API externes et batchs d’une meme forme AppError a raccourci les prompts. Au lieu de “corrige cette erreur proprement”, il peut demander: validation retourne 400, external utilise retryable, job conserve attempt. La revue se concentre alors sur trois surfaces: reponse, log et test. Ce n’est pas une architecture magique, mais c’est bien plus exploitable qu’un systeme rempli de 500 anonymes.