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é.
{
"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 :
{
"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
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.
