Error Codes & Idempotency
Standardized error responses, HTTP status codes, and retry strategies.
Tumr returns standard HTTP response codes alongside a consistent {"error": {...}} envelope:
{
"error": {
"type": "validation_error",
"code": "INVALID",
"message": "dropoff_latitude is required.",
"details": {
"dropoff_latitude": ["This field is required."]
}
}
}type groups the failure (validation_error, authentication_error, permission_error, not_found, rate_limit_exceeded, server_error), code is a stable machine-readable code, and details carries field-level detail when available.
HTTP Status Codes
| Code | Status | Cause |
| :--- | :--- | :--- |
| 200 OK | Success | Request succeeded. |
| 201 Created | Created | New shipment or API 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 Usage Balance | A paid action (e.g. an AI task) exceeds the usage wallet balance. |
| 404 Not Found | Resource Missing | Shipment UUID or tracking ID does not exist. |
| 409 Conflict | State Conflict | Attempting an action incompatible with the resource state. |
| 429 Too Many Requests | Rate Limited | The applicable throttle quota was exceeded; the response detail states when to retry. |
| 500 Internal Error | Server Exception | Tumr platform issue. Safely retry POSTs that support an Idempotency-Key. |