> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nexspace365.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Prevent duplicate operations with Idempotency-Key headers

# 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

```bash theme={null}
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

| Scenario                  | Result                                          |
| ------------------------- | ----------------------------------------------- |
| New key                   | Execute normally, cache response                |
| Same key + same body      | Replay cached response (HTTP status preserved)  |
| Same key + different body | `409 Conflict`                                  |
| Key expires (24h)         | Treated as new key                              |
| GET/DELETE requests       | Header 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