Idempotency
Network failures happen. Idempotency keys let you safely retry order creation requests without the risk of creating duplicate deliveries. Send the same key, get the same result.
How It Works
Include the X-Idempotency-Key header in your POST /v1/business/order/create requests. The key can be any unique string up to 255 characters -- common choices include UUIDs, order reference IDs, or composite keys.
First Request
The order is created normally. The key and response are cached.
Retry (Same Key + Same Body)
The cached response is returned. No duplicate order is created.
Same Key + Different Body
Returns a 409 IDEMPOTENCY_CONFLICT error.
| Property | Details |
|---|---|
| Header | X-Idempotency-Key |
| Applies To | POST /v1/business/order/create |
| Cache Duration | 24 hours from the first request |
| Scope | Per partner (API key). Two different partners can use the same key string without conflict. |
| Max Length | 255 characters |
Code Examples
The following examples show how to include an idempotency key when creating an order.
curl -X POST https://api.pathao.com/v1/business/order/create \
-H "X-API-Key: your_api_key" \
-H "X-Idempotency-Key: ord-20250119-abc123-v1" \
-H "Content-Type: application/json" \
-d '{
"pickup_latitude": 23.7937,
"pickup_longitude": 90.4066,
"delivery_latitude": 23.7465,
"delivery_longitude": 90.3762,
"receiver_name": "John Doe",
"receiver_phone": "01700000001",
"parcel_type": 2,
"driver_type": 1
}'When to Use Idempotency Keys
- •Network timeouts. Your request may have reached the server but the response was lost. Retrying with the same key is always safe.
- •User double-clicks. If a user submits an order form twice, both requests can share the same idempotency key to prevent duplicates.
- •Background job retries. If your job worker crashes mid-request, it can safely retry using the same key when it restarts.
- •Any non-idempotent mutation. Order creation is inherently non-idempotent. Always include the header as a safety measure.
IDEMPOTENCY_CONFLICT Error
If you reuse an idempotency key with a different request body (for example, different coordinates or a different receiver), the API returns a 409 Conflict response. This protects against accidental key reuse across different orders.
To resolve this error, generate a new unique idempotency key for the new order request. Each unique order should always use its own key.