Error Handling
The ColisMove API returns consistent error responses using standard HTTP status codes and a structured JSON body.
{
"status": 400,
"error": "Bad Request",
"message": "Le prix par kilo doit etre positif",
"timestamp": "2026-04-13T10:30:00Z",
"path": "/v1/api/annonces"
}
HTTP Status Codes
| Code | Meaning | When |
|---|
400 | Bad Request | Validation error, missing required field, invalid format |
401 | Unauthorized | Missing or expired JWT token |
403 | Forbidden | Insufficient role (e.g., non-verified user creating an announcement) |
404 | Not Found | Resource does not exist |
409 | Conflict | Duplicate resource (e.g., email already registered) |
422 | Unprocessable Entity | Business rule violation (e.g., invalid booking state transition) |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Unexpected server error |
Validation Errors
For field-level validation errors, the response includes details about each invalid field:
{
"status": 400,
"error": "Bad Request",
"message": "Validation failed",
"fieldErrors": [
{
"field": "email",
"message": "must be a valid email address"
},
{
"field": "password",
"message": "must be at least 8 characters"
}
]
}
Domain Errors
Business rule violations return descriptive French-language messages:
| Error | Description |
|---|
Annonce non trouvee | Announcement not found |
Reservation non trouvee | Booking not found |
Transition invalide | Invalid state transition for a booking |
Utilisateur non verifie | User has not completed KYC verification |
Solde insuffisant | Insufficient wallet balance for withdrawal |
Rate Limiting
Certain endpoints are rate-limited. When exceeded, you receive:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Implement exponential backoff when receiving 429 responses. The Retry-After header indicates how many seconds to wait.
