Skip to main content

​
Idempotency

Write operations (POST, PUT, PATCH) accept an Idempotency-Key header to prevent duplicate actions when agents or integrations retry requests.

​
How It Works

  1. Generate a unique key (UUID recommended) for each logical operation
  2. Send it in the Idempotency-Key header
  3. If the same key is sent again within 24 hours with the same body, the original response is replayed without re-executing the operation
  4. If the same key is sent with a different body, you get 409 Conflict

​
Example

curl -X POST https://api.nexspace365.com/api/shifts/123/assign \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"staffIds": [456]}'
Sending the exact same request again replays the original response — the staff member is not assigned twice.

​
Behavior

ScenarioResult
New keyExecute normally, cache response
Same key + same bodyReplay cached response (HTTP status preserved)
Same key + different body409 Conflict
Key expires (24h)Treated as new key
GET/DELETE requestsHeader ignored (these are naturally idempotent)

​
Key Requirements

  • Minimum 8 characters, maximum 256 characters
  • Must be unique per logical operation
  • UUID v4 recommended: crypto.randomUUID()

​
Best Practices

  • Always include Idempotency-Key on mutation endpoints
  • Store the key alongside your operation log for debugging
  • Use a deterministic key (e.g., ${orderId}-assign-${staffId}) when retrying the same logical operation