Idempotency - CrossBorderly API

What is Idempotency?

Idempotency ensures that making the same API request multiple times produces the same result as making it once. This is critical for:

Network failures: Retry safely without creating duplicates
Timeouts: Resubmit requests that timed out
Distributed systems: Handle concurrent requests

How It Works

Include an idempotencyKey in your POST requests:

{
  "idempotencyKey": "order-12345-abc",
  ...
}

If you send the same key within 24 hours:

The system recognizes the duplicate
Returns the original response without re-executing
No duplicate resources are created

Implementation

Generate Unique Keys

Use a consistent strategy for generating keys:

// Option 1: Use your order ID
const idempotencyKey = `order-${orderId}`;

// Option 2: UUID
const idempotencyKey = crypto.randomUUID();

// Option 3: Composite key
const idempotencyKey = `${customerId}-${orderId}-${timestamp}`;

Example: Safe Order Creation

async function createOrder(order) {
  // Key based on your order ID ensures idempotency
  const idempotencyKey = `create-order-${order.id}`;
  
  try {
    const response = await fetch('https://api.crbtrack.com/api/v1/orders/create', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        idempotencyKey,
        ...orderData
      })
    });
    
    const data = await response.json();
    return data;
    
  } catch (error) {
    // Safe to retry - same idempotencyKey won't create duplicate
    if (shouldRetry(error)) {
      return createOrder(order);  // Same key = same result
    }
    throw error;
  }
}

Idempotency Rules

Key Requirements

Length: 8-64 characters
Characters: Alphanumeric, hyphens, underscores
Uniqueness: Must be unique per operation type
Expiry: Keys expire after 24 hours

Scope

Keys are scoped to your API key (not global)
Same key can be used for different endpoints
Example: order-123 for /orders/create is different from order-123 for /orders/void

Response Behavior

First request: Operation executes, response cached
Duplicate request: Cached response returned (HTTP 200)
Different payload, same key: Error returned (409 Conflict)

Endpoints Supporting Idempotency

Endpoint	idempotencyKey
`POST /api/v1/orders/create`	Required
`POST /api/v1/manifests/submit`	Optional
`POST /api/v1/orders/void`	Required
`POST /api/v1/labels/{id}/reprint`	Required

Common Patterns

Pattern 1: Order ID as Key

Best for e-commerce integrations:

const idempotencyKey = `order-${order.id}`;

✅ Simple and predictable
✅ Natural deduplication if order already processed
✅ Easy to debug

Pattern 2: Request Hash

Best for operations without natural IDs:

const idempotencyKey = crypto
  .createHash('sha256')
  .update(JSON.stringify(requestBody))
  .digest('hex')
  .substring(0, 32);

✅ Automatically detects identical requests
⚠️ Different results for slightly different payloads

Pattern 3: Timestamp + ID

Best for retry-heavy workflows:

const idempotencyKey = `${customerId}-${action}-${Date.now()}`;

⚠️ Generates new key on each attempt
⚠️ Doesn’t prevent accidental duplicates

Handling Conflicts

If you send a different payload with the same key:

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Request payload differs from original request with this idempotencyKey"
  }
}

Resolution: Generate a new unique key for the modified request.

Best Practices

Do

Use predictable keys (order IDs)
Store keys with requests for debugging
Retry with same key on failures

Don't

Generate random keys per retry
Reuse keys for different operations
Rely on idempotency for business logic

​What is Idempotency?

​How It Works

​Implementation

​Generate Unique Keys

​Example: Safe Order Creation

​Idempotency Rules

​Endpoints Supporting Idempotency

​Common Patterns

​Pattern 1: Order ID as Key

​Pattern 2: Request Hash

​Pattern 3: Timestamp + ID

​Handling Conflicts

​Best Practices

Do