​

Idempotency

​

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]}'

​

Behavior

​

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