Erreurs

Toutes les erreurs respectent un format uniforme avec un code HTTP standard et un code métier stable pour faciliter le traitement programmatique.

Format d’une erreur

{
  "code": "CUSTOMER_NOT_FOUND",
  "message": "Client non trouvé",
  "details": { /* optionnel */ }
}

• code : identifiant stable — faites votre logique dessus, pas sur message
• message : phrase en français destinée à être affichée (peut changer entre versions)
• details : objet optionnel avec des infos supplémentaires (ex: erreurs de validation par champ)

Exemple — erreur de validation

{
  "code": "VALIDATION_ERROR",
  "message": "Requête invalide",
  "details": {
    "email": ["Requis pour la création"],
    "name": ["Requis pour la création"]
  }
}

Codes d’erreur par domaine

Authentification

Code HTTP	Code métier	Quand ?
401	AUTH_API_KEY_MISSING	Header X-API-Key absent
401	AUTH_API_KEY_INVALID	Clé mal formatée ou ne correspondant à aucune app
403	AUTH_API_KEY_FORBIDDEN	Clé publique (pk_live_) utilisée sur une route server-only

Validation

Code HTTP	Code métier	Quand ?
400	VALIDATION_ERROR	Body invalide — voir details pour le détail par champ

Clients

Code HTTP	Code métier	Quand ?
404	CUSTOMER_NOT_FOUND	externalId inconnu dans votre app
409	CUSTOMER_EMAIL_EXISTS	Email déjà pris par un autre client de votre app

Tickets

Code HTTP	Code métier	Quand ?
403	PLAN_LIMIT_REACHED	Quota mensuel de tickets atteint
404	TICKET_NOT_FOUND	ID de ticket inconnu (routes de lecture)

Génériques

Code HTTP	Code métier	Quand ?
429	TOO_MANY_REQUESTS	Rate limit global dépassé (3 req/s, 20 req/10s, 100 req/min)
500	INTERNAL_ERROR	Erreur serveur — à remonter au support si persistant

Bonnes pratiques côté client

• Retry uniquement sur 5xx et 429. Sur un 4xx, corriger la requête plutôt que de retenter.
• Exponential backoff sur 429 : 1s, 2s, 4s, 8s…
• Pivoter sur le code métier, pas sur le message FR qui peut évoluer.
• Logguer code + details pour vos traces internes.

Exemple de handler Node.js

async function callSupportDesk(path, body) {
  const res = await fetch(`https://supportdesk.innovartx.com/api/v1${path}`, {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.SUPPORTDESK_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  if (!res.ok) {
    const err = await res.json().catch(() => null);
    const code = err?.code ?? 'UNKNOWN';

    if (code === 'CUSTOMER_NOT_FOUND') {
      // logique métier spécifique
    }
    throw new Error(`SupportDesk ${res.status} ${code}`);
  }

  return res.json();
}