> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ligdicash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestion des erreurs — Vue d'ensemble

> Comprendre les deux niveaux d'erreur de l'API LigdiCash : rejet de la requête (response_code) et échec de la transaction (callback/confirm).

L'API LigdiCash distingue deux niveaux d'erreur qu'il est essentiel de ne pas confondre : le rejet immédiat d'une requête malformée, et l'échec d'une transaction pourtant bien initiée. Ce guide explique comment traiter chacun.

## Les deux niveaux d'erreur

### Niveau 1 — Rejet de la requête (response\_code)

Survient immédiatement à l'appel HTTP. LigdiCash a lu votre payload et le rejette.

| `response_code` | Signification                                                     |
| --------------- | ----------------------------------------------------------------- |
| `00`            | Payload valide — la transaction est initiée                       |
| `01`            | Payload invalide ou erreur d'authentification — rien n'a été créé |

Quand `response_code` vaut `01`, le champ `response_text` contient un sous-code technique de la forme `Echec (CodeXX)`. Consultez le champ `wiki` pour en obtenir la description lisible.

<Warning>
  `response_code: "00"` ne garantit pas que le paiement aboutira. C'est uniquement la confirmation que votre requête était syntaxiquement correcte et que la transaction a été mise en file d'attente. Le résultat réel du paiement est communiqué via le callback ou l'endpoint `confirm`.
</Warning>

### Niveau 2 — Échec de la transaction (callback / confirm)

Survient après `response_code: "00"`. La transaction a été initiée mais n'a pas abouti côté opérateur.

| Champ                        | Valeur en cas d'échec                    |
| ---------------------------- | ---------------------------------------- |
| `status` dans le callback    | `notcompleted`                           |
| `response_code` de `confirm` | `01` avec sous-code dans `response_text` |

Ces échecs indiquent des problèmes métier : solde insuffisant, OTP incorrect, numéro non éligible, etc.

***

## Les catégories d'erreur

| Catégorie                  | Quand              | Exemples                                                       |
| -------------------------- | ------------------ | -------------------------------------------------------------- |
| **Authentification**       | Immédiat           | Apikey invalide, token expiré                                  |
| **Payload invalide**       | Immédiat           | Champ manquant, format de numéro incorrect, montant non entier |
| **Erreur opérateur**       | Différé (callback) | Annulation                                                     |
| **Erreur métier marchand** | Immédiat           | Payout non activé sur le compte, plafond dépassé               |
| **Erreur technique**       | Immédiat           | Timeout, service indisponible                                  |

***

## Stratégie générale de traitement

<Steps>
  <Step title="Vérifier response_code immédiatement">
    Si `response_code === "01"` : loggez `response_text`, consultez l'URL dans `wiki` pour la description lisible. Ne pas lancer de retry immédiat — corriger d'abord la cause.
  </Step>

  <Step title="Stocker le token de création">
    Si `response_code === "00"` : stocker le `token` retourné dans votre base de données, associé à votre `transaction_id`. Vous en aurez besoin pour re-vérifier le callback.
  </Step>

  <Step title="Traiter le callback de façon défensive">
    Ne jamais faire confiance au payload callback seul. Toujours appeler `confirm` avec le token stocké à l'étape précédente pour valider l'issue réelle.
  </Step>
</Steps>

***

## Exemple de traitement complet

```javascript Node.js theme={null}
async function initierPaiement(payload) {
  const res = await fetch("https://app.ligdicash.com/pay/v01/straight/checkout-invoice/create", {
    method: "POST",
    headers: {
      "Apikey": process.env.LIGDICASH_API_KEY,
      "Authorization": `Bearer ${process.env.LIGDICASH_AUTH_TOKEN}`,
      "Accept": "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  const data = await res.json();

  if (data.response_code === "01") {
    // Niveau 1 — rejet immédiat
    logger.error({
      event: "ligdicash_request_rejected",
      subcode: data.response_text,  // ex: "Echec (Code00)"
      wiki: data.wiki,              // URL pour la description lisible
    });
    throw new Error(`Requête rejetée : ${data.response_text}`);
  }

  // response_code === "00" : transaction initiée
  // Stocker le token pour la re-vérification callback
  await db.transactions.create({
    transaction_id: payload.custom_data[0].valueof_customdata,
    ligdicash_token: data.token,
    status: "pending",
  });

  return data;
}
```

***

## Pages associées

* [Le champ wiki](/erreurs/champ-wiki) — comment décoder `Echec (CodeXX)` en message lisible
* [Liste des sous-codes](/erreurs/sous-codes) — référence complète par endpoint
* [Erreurs courantes](/erreurs/erreurs-courantes) — causes et solutions
* [Codes de réponse et statuts](/concepts/codes-reponse-statuts) — référence complète de `response_code`
* [Sécurisation du callback](/api-paiement/callback/securisation) — re-vérification via `confirm`