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

# Gestion des erreurs

> Réponses d'erreur standardisées sur l'ensemble des endpoints de l'API

# Gestion des erreurs

L'API ColisMove retourne des réponses d'erreur cohérentes en s'appuyant sur les codes de statut HTTP standards et un corps JSON structuré.

## Format de réponse d'erreur

```json theme={null}
{
  "status": 400,
  "error": "Bad Request",
  "message": "Le prix par kilo doit être positif",
  "timestamp": "2026-04-13T10:30:00Z",
  "path": "/v1/api/annonces"
}
```

## Codes de statut HTTP

| Code  | Signification         | Quand                                                                            |
| ----- | --------------------- | -------------------------------------------------------------------------------- |
| `400` | Bad Request           | Erreur de validation, champ requis manquant, format invalide                     |
| `401` | Unauthorized          | Token JWT manquant ou expiré                                                     |
| `403` | Forbidden             | Rôle insuffisant (ex : utilisateur non vérifié créant une annonce)               |
| `404` | Not Found             | Ressource inexistante                                                            |
| `409` | Conflict              | Ressource dupliquée (ex : email déjà enregistré)                                 |
| `422` | Unprocessable Entity  | Violation de règle métier (ex : transition d'état invalide pour une réservation) |
| `429` | Too Many Requests     | Limite de débit dépassée                                                         |
| `500` | Internal Server Error | Erreur serveur inattendue                                                        |

## Erreurs de validation

Pour les erreurs de validation au niveau des champs, la réponse inclut le détail de chaque champ invalide :

```json theme={null}
{
  "status": 400,
  "error": "Bad Request",
  "message": "La validation a échoué",
  "fieldErrors": [
    {
      "field": "email",
      "message": "doit être une adresse email valide"
    },
    {
      "field": "password",
      "message": "doit contenir au moins 8 caractères"
    }
  ]
}
```

## Erreurs métier

Les violations de règles métier retournent des messages descriptifs en français :

| Erreur                    | Description                                       |
| ------------------------- | ------------------------------------------------- |
| `Annonce non trouvée`     | Annonce inexistante                               |
| `Réservation non trouvée` | Réservation inexistante                           |
| `Transition invalide`     | Transition d'état invalide pour une réservation   |
| `Utilisateur non vérifié` | L'utilisateur n'a pas terminé sa vérification KYC |
| `Solde insuffisant`       | Solde du portefeuille insuffisant pour le retrait |

## Limitation de débit

Certains endpoints sont soumis à une limite de débit. En cas de dépassement, vous recevez :

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

<Tip>
  Implémentez un backoff exponentiel lorsque vous recevez des réponses 429. L'en-tête `Retry-After` indique le nombre de secondes à attendre avant de réessayer.
</Tip>