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

# Gestion des erreurs

> Codes d erreur, résolution et bonnes pratiques

## Structure des erreurs

```json theme={null}
{
  "statusCode": 400,
  "message": "Le montant doit être supérieur à 100 XOF",
  "error": "Bad Request"
}
```

## Codes HTTP

| Code  | Signification         | Action                   |
| ----- | --------------------- | ------------------------ |
| `200` | Succès                | -                        |
| `400` | Requête invalide      | Vérifier les paramètres  |
| `401` | Non authentifié       | Vérifier la clé API      |
| `403` | Accès refusé          | Vérifier les permissions |
| `404` | Ressource non trouvée | Vérifier l'identifiant   |
| `422` | Erreur métier         | Voir le code d'erreur    |
| `429` | Trop de requêtes      | Attendre et réessayer    |
| `500` | Erreur serveur        | Contacter le support     |

## Erreurs de validation

| Champ           | Règle                  | Message                                       |
| --------------- | ---------------------- | --------------------------------------------- |
| `amount`        | Min: 100, Max: 5000000 | "Le montant doit être entre 100 et 5 000 000" |
| `currency`      | XOF, XAF, EUR, USD     | "Devise non supportée"                        |
| `customerPhone` | Format E.164           | "Format de numéro invalide"                   |
| `provider`      | Valeur valide          | "Méthode de paiement invalide"                |

## Erreurs de paiement

| Code                 | Description              | Action                   |
| -------------------- | ------------------------ | ------------------------ |
| `insufficient_funds` | Solde client insuffisant | Informer le client       |
| `user_cancelled`     | Annulé par le client     | Proposer de réessayer    |
| `timeout`            | Délai expiré             | Réinitier le paiement    |
| `provider_error`     | Erreur du provider       | Réessayer plus tard      |
| `invalid_phone`      | Numéro invalide          | Vérifier le format E.164 |

## Erreurs de payout

| Code                   | Description             | Action                     |
| ---------------------- | ----------------------- | -------------------------- |
| `invalid_recipient`    | Bénéficiaire invalide   | Vérifier le numéro/compte  |
| `insufficient_balance` | Votre solde insuffisant | Recharger votre compte     |
| `provider_error`       | Erreur du provider      | Réessayer plus tard        |
| `limit_exceeded`       | Limite dépassée         | Vérifier `/payouts/limits` |
| `account_blocked`      | Compte bloqué           | Contacter le support       |

## Rate limiting

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800
```

En cas de `429 Too Many Requests`, attendez le timestamp `X-RateLimit-Reset` avant de réessayer.

## Erreurs d'intégration courantes

<AccordionGroup>
  <Accordion title="Se fier à la redirection au lieu du webhook">
    Le `returnUrl` ne garantit pas le succès. Attendez toujours le webhook `payment.completed`.
  </Accordion>

  <Accordion title="Clé secrète exposée côté client">
    N'utilisez jamais `sk_*` dans du JavaScript navigateur. La clé secrète reste côté serveur uniquement.
  </Accordion>

  <Accordion title="Mauvais format de numéro">
    Envoyez `+221771234567` (E.164), pas `771234567` ou `00221771234567`.
  </Accordion>

  <Accordion title="Mélange d'environnements">
    Les clés `sk_test_*` ne fonctionnent qu'avec `sandbox-api.caurisflux.com`. Les clés `sk_live_*` uniquement avec `prod-api.caurisflux.com`.
  </Accordion>

  <Accordion title="transaction_id non sauvegardé">
    Stockez toujours le `transactionId` retourné. Sans lui, impossible de lier le webhook à votre commande.
  </Accordion>
</AccordionGroup>