Gestion des erreurs

Lors de l’intégration avec lomi., il est essentiel de gérer les erreurs proprement afin d’offrir une expérience de paiement fluide à vos clients.

lomi. utilise les codes de réponse HTTP habituels et renvoie des messages d’erreur exploitables pour diagnostiquer les problèmes et informer vos clients de l’état de leurs transactions.

Consultez la référence des erreurs pour la liste détaillée des codes de statut et des réponses d’erreur courantes.

Format des réponses d’erreur

Toutes les erreurs d’API suivent une structure JSON cohérente :

{
  "error": {
    "code": "bad_request",
    "message": "Description lisible de l’erreur.",
    "details": "Facultatif : contexte ou données structurées supplémentaires sur l’erreur."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Gestion des types d’erreurs courants

Erreurs de validation (HTTP 400)

Elles surviennent lorsque les données de la requête sont invalides ou que des champs obligatoires manquent.

import { LomiSDK, LomiError } from '@lomi./sdk'; // En supposant que le SDK exporte le type d’erreur

const lomi = new LomiSDK({ apiKey: process.env.LOMI_API_KEY! });

try {
  const session = await lomi.checkoutSessions.createCheckoutSession({
    amount: -100, // Invalide : doit être positif
    currency_code: 'INVALID', // Valeur d’énumération invalide
    // Champs obligatoires manquants comme success_url, cancel_url
  });
} catch (error) {
  if (error instanceof LomiApiError && error.statusCode === 400) {
    console.error('Validation failed:', error.message);
    // Journaliser ou afficher les détails disponibles dans error.details
    console.error('Details:', error.details);
    // Informer l’utilisateur des problèmes de saisie précis
  } else {
    // Gérer les autres types d’erreurs
    console.error('An unexpected error occurred:', error);
  }
}

Erreurs d’authentification (HTTP 401)

Elles surviennent lorsque la LOMI_API_KEY est absente, invalide ou ne dispose pas des autorisations nécessaires.

import { LomiSDK, LomiError } from '@lomi./sdk';

const lomi = new LomiSDK({ apiKey: 'invalid-key' });

try {
  await lomi.providers.listProviders(); // Exemple de requête
} catch (error) {
  if (error instanceof LomiApiError && error.statusCode === 401) {
    console.error('Authentication failed:', error.message);
    // Vérifications courantes :
    if (!process.env.LOMI_API_KEY) {
      console.error(
        'Suggestion : la variable d’environnement LOMI_API_KEY est peut-être absente.',
      );
    } else {
      console.error(
        'Suggestion : vérifiez que LOMI_API_KEY est correcte et active.',
      );
    }
  } else {
    console.error('An unexpected error occurred:', error);
  }
}

Erreurs de limite de débit (HTTP 429)

Elles surviennent lorsque vous dépassez le nombre de requêtes autorisées sur une fenêtre donnée (par ex. 100 requêtes par 15 minutes).

import { LomiSDK, LomiError } from '@lomi./sdk';

const lomi = new LomiSDK({ apiKey: process.env.LOMI_API_KEY! });

async function makeRequestWithRateLimitHandling() {
  try {
    const response = await lomi.providers.listProviders();
    // Traiter la réponse en cas de succès
  } catch (error) {
    if (error instanceof LomiApiError && error.statusCode === 429) {
      console.warn('Rate limit exceeded. Retrying after delay...');
      // Extraire l’en-tête Retry-After si disponible (selon le SDK ou fetch)
      const retryAfterSeconds = error.headers?.['retry-after']
        ? parseInt(error.headers['retry-after'], 10)
        : 60;
      await new Promise((resolve) =>
        setTimeout(resolve, retryAfterSeconds * 1000),
      );
      // Réessayer la requête (logique de nouvelle tentative adaptée ; voir ci-dessous)
      // await makeRequestWithRateLimitHandling();
    } else {
      console.error('An unexpected error occurred:', error);
    }
  }
}

Erreurs serveur (HTTP 5xx)

Elles indiquent un problème côté lomi.. Elles doivent rester rares. Il est généralement acceptable de réessayer ces requêtes après un délai.

Bonnes pratiques

Dégradation gracieuse :
- Anticipez les échecs d’API possibles.
- Proposez un retour utilisateur clair plutôt que le message d’erreur brut.
- Prévoyez des mécanismes de secours si une opération critique échoue (par ex. traitement manuel de la commande).
- Journalisez les détails côté serveur (y compris les identifiants de requête si disponibles) pour le débogage, sans exposer d’informations sensibles au client.

Stratégie de nouvelle tentative (recul exponentiel et jitter) : Mettez en place une logique de nouvelle tentative pour les erreurs réseau, les limites de débit (429) et les erreurs serveur (5xx). Évitez de réessayer les erreurs client (4xx sauf 429) : elles exigent en général de corriger la requête.

async function withRetry<T>(
  asyncFn: () => Promise<T>,
  maxRetries = 3,
  initialDelayMs = 1000,
): Promise<T> {
  let attempts = 0;
  while (true) {
    try {
      return await asyncFn();
    } catch (error: any) {
      attempts++;
      const isRetryable =
        error instanceof LomiError &&
        (error.statusCode === 429 || error.statusCode >= 500);

      if (!isRetryable || attempts >= maxRetries) {
        // Ne pas réessayer les erreurs client (sauf 429) ni au-delà du max
        throw error;
      }

      // Délai avec recul exponentiel et jitter
      const delay = initialDelayMs * Math.pow(2, attempts - 1);
      const jitter = delay * 0.2 * Math.random(); // Environ +/- 10 % de jitter
      const waitTime = Math.max(100, delay + jitter); // Délai minimum

      console.warn(
        `Attempt ${attempts} failed. Retrying in ${waitTime.toFixed(0)}ms...`,
        error.message,
      );
      await new Promise((resolve) => setTimeout(resolve, waitTime));
    }
  }
}

// Exemple d’usage :
// const providers = await withRetry(() => lomi.providers.list());

Surveillance des erreurs :
- Utilisez un service de monitoring applicatif (par ex. Sentry, Datadog) pour suivre les erreurs en production.
- Surveillez les taux et schémas d’erreurs pour repérer les problèmes systémiques.
- Configurez des alertes sur les erreurs critiques ou les pics inhabituels.