# Error Codes & Idempotency
Tumr returns standard HTTP response codes alongside structured JSON error objects:
{
"error": {
"code": "INSUFFICIENT_FUNDS",
"message": "Your wallet available balance (₦1,200.00) is insufficient for this booking (₦2,500.00).",
"details": {
"required_amount": "2500.00",
"available_balance": "1200.00",
"currency": "NGN"
}
}
}HTTP Status Codes
| Code | Status | Cause |
| :--- | :--- | :--- |
| 200 OK | Success | Request succeeded. |
| 201 Created | Created | New shipment, webhook, or key generated. |
| 400 Bad Request | Validation Error | Missing or invalid payload parameter. |
| 401 Unauthorized | Auth Failure | Invalid API Key or expired JWT token. |
| 402 Payment Required | Insufficient Escrow | Wallet available balance too low to lock order fare. |
| 404 Not Found | Resource Missing | Shipment UUID or tracking ID does not exist. |
| 409 Conflict | State Conflict | Attempting to cancel an order already in transit. |
| 429 Too Many Requests | Rate Limited | Exceeded 120 requests/minute. |
| 500 Internal Error | Server Exception | Tumr platform issue. Safely retry with an Idempotency-Key. |