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

# Erreurs

> Codes de statut et gestion des erreurs.

Les erreurs renvoient un statut HTTP différent de 2xx et une enveloppe où `success` vaut
`false` :

```json theme={null}
{
  "success": false,
  "message": "Insufficient permissions. Required scope: pay",
  "request_id": "b2f1c3a0-...",
  "required_scopes": ["pay"]
}
```

Branchez toujours votre logique sur le code de statut HTTP et affichez `message` pour le
débogage. Journalisez `request_id` : indiquez-le lorsque vous contactez le support.

## Codes de statut

| Code  | Signification     | Causes fréquentes                                                                  |
| ----- | ----------------- | ---------------------------------------------------------------------------------- |
| `200` | OK                | Lecture réussie ou écriture synchrone                                              |
| `201` | Created           | Ressource créée (payout, bénéficiaire, webhook, …)                                 |
| `202` | Accepted          | Traitement asynchrone démarré — **pas encore réglé** (`/pay`, `/process` d'un lot) |
| `400` | Bad Request       | Champs manquants ou invalides, refus de l'opérateur, solde insuffisant             |
| `401` | Unauthorized      | Token ou clé API manquant, invalide ou expiré                                      |
| `403` | Forbidden         | Scope requis absent du token, compte inactif, ou IP hors liste blanche             |
| `404` | Not Found         | L'identifiant n'existe pas ou ne vous appartient pas                               |
| `409` | Conflict          | `reference` en double, ou slug déjà pris                                           |
| `429` | Too Many Requests | Limite de débit atteinte (ex. `/auth` : 20 par 15 min)                             |
| `500` | Server Error      | Erreur inattendue — réessayez avec un délai croissant, puis contactez le support   |

## Idempotence et doublons

`/pay` et `/deposit` acceptent une `reference`. Si vous renvoyez une requête avec une
`reference` déjà utilisée, vous recevez un `409` accompagné de la transaction existante :

```json theme={null}
{
  "success": false,
  "message": "Transaction with this reference already exists",
  "existing_transaction": { "id": 88213, "status": "pending" }
}
```

Définissez toujours une `reference` stable et unique par transaction logique, afin qu'une
nouvelle tentative ne crée pas de double débit.

## Gérer les paiements en attente

Un `202` renvoyé par `/pay` n'est **pas** un paiement abouti. Interrogez
`GET /merchant/api/transactions/{id}` ou attendez le
[webhook `payment_received`](/fr/webhooks). Voir
[Statut d'un paiement](/fr/payment-status). Les valeurs de `status` que vous pouvez
rencontrer :

| Statut       | Signification                                          |
| ------------ | ------------------------------------------------------ |
| `pending`    | Demande envoyée ; en attente de confirmation du client |
| `processing` | Règlement en cours                                     |
| `success`    | Abouti et crédité                                      |
| `failed`     | Refusé ou impossible à finaliser                       |
| `cancelled`  | Annulé avant la fin                                    |
| `reversed`   | Abouti puis contrepassé                                |
| `expired`    | Le client n'a pas confirmé à temps                     |