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

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

​Gestion des erreurs

​Format de réponse d’erreur

​Codes de statut HTTP

​Erreurs de validation

​Erreurs métier

​Limitation de débit

Gestion des erreurs

Format de réponse d’erreur

Codes de statut HTTP

Erreurs de validation

Erreurs métier

Limitation de débit