Idempotency (Duplicate Request Protection)

Idempotency is a mechanism that ensures a request is processed only once, even if it is sent multiple times. This feature prevents duplicate records from being created, especially in cases of network issues or timeouts.

When to Use?

The idempotency feature is critical in the following scenarios:

Scenario	Description
Network Timeout	The request reached the server and was processed, but the response failed to reach the client. When the client resends the request, a duplicate record may be created.
Connection Drop	The connection was lost while sending the request, and it's unclear whether the request was processed.
Retry Mechanism	In systems with automatic retry mechanisms, the same request may be sent multiple times.

Example Scenario: You sent a request to create a consignment. The server created the consignment, but the connection dropped while returning the response. Your system resent the request. Without idempotency, two separate consignments would be created.

How to Use?

To use the idempotency feature, simply add the X-Idempotency-Key header to your request.

Header	Value	Required
`X-Idempotency-Key`	Unique string (UUID, order number, etc.)	OPTIONAL

Note: If this header is not sent, no idempotency check is performed and the request is processed normally.

Example Request

curl -X POST "{{BASE_URL}}/api/v1/consignments" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -H "X-Idempotency-Key: order-12345-shipment-001" \
  -d '{
    "provider_id": 1,
    "preference": 0,
    ...
  }'

Behavior

First Request

The request is processed normally and the successful response is cached.

Repeat Request with Same Key

When a request with the same X-Idempotency-Key is received within a certain period:

The request is not processed again
The previous successful response is returned

Error Responses

If the first request resulted in an error (HTTP 4xx or 5xx), the response is not cached. This allows failed requests to be corrected and resent.

Response Headers

The following headers are added to successful responses when idempotency is active:

Header	Description
`X-Idempotency-Key`	The idempotency key value that was sent
`X-Idempotency-Stored-At`	Time when the response was cached (Unix timestamp)

Supported Endpoints

The following endpoints support the idempotency feature:

Endpoint	Method	Description
`/api/v1/consignments`	POST	Create domestic/international consignment
`/api/v1/consignments/multi-package`	POST	Create multi-package consignment
`/api/v1/consignments/draft`	POST	Create draft consignment

Key Selection Recommendations

Consider the following recommendations when choosing an idempotency key:

Recommendation	Description
Must be unique	Use a different key for each different operation
Must be predictable	You should be able to generate the same key for the same operation
Should be tied to business logic	Use unique values from your business logic such as order number, transaction ID

Recommended Key Formats

# Order-based
order-{order_no}-shipment

# UUID
550e8400-e29b-41d4-a716-446655440000

# Date + operation based
2024-01-15-order-12345

Warning: Randomly generated keys (e.g., new UUID for each retry) defeat the purpose of idempotency. The key should always produce the same value for the same operation.