Idempotency and duplicates

Networks fail mid-request. These rules mean a retry cannot turn one customer request into two refunds.

Key

Sending an idempotency key

Send a stable key on any request that creates something. Resending with the same key returns the original result instead of creating a second record.

curl -sS -X POST https://api.simcoai.co.uk/v1/refunds \
  -H "X-SIMCOAI-API-Key: $SIMCOAI_API_KEY" \
  -H "X-SIMCOAI-Idempotency-Key: refund-ORD2048-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"order_number":"ORD-2048","reason":"Damaged on arrival"}'

Derive the key from something stable in your system — an order id plus an action — not from a timestamp or a random value generated per attempt.

Duplicates

Server-side duplicate prevention

Workflow tables carry their own protection, so even without a key SIMCOAI will not silently create a second refund for the same order.

A duplicate attempt returns 409 with WORKFLOW_DUPLICATE.

Expected result

Your integration should treat 409 WORKFLOW_DUPLICATE as success: the work already exists and a person will review it. Fetch the existing record if you need its id.

Upsert

Orders behave as upserts

Posting an order with an order_number that already exists updates that record rather than creating a duplicate. That makes order sync safe to re-run.

This is why order_number is required on order creation — it is the key SIMCOAI matches on.