Idempotency

POST and PATCH requests support the Idempotency-Key header. If a request fails due to a network error, you can safely retry with the same key — the API returns the original response without duplicating the operation.

---

How it works

1. Generate a unique key (UUIDv4 recommended) for each distinct operation
2. Include it in the Idempotency-Key header on the first attempt
3. If the request times out or fails before you receive a response, retry with the same key
4. The API returns the original response; no duplicate record is created

Keys are retained for 30 days. After 30 days the key expires; the same key can be reused for a new distinct operation.

---

Usage

curl

curl -X POST https://api.xavigate.com/v1/nature/subjects \
  -H "Authorization: Bearer test_sk_YOUR_KEY" \
  -H "Idempotency-Key: 8e9c4f2a-3b1d-4e5f-9a8b-7c6d5e4f3a2b" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

TypeScript

// The SDK auto-generates Idempotency-Key on every retryable request
// No configuration needed by default.

// To supply your own key (e.g., for application-level dedup):
await client.nature.subjects.create({ ... }, {
  idempotencyKey: '8e9c4f2a-3b1d-4e5f-9a8b-7c6d5e4f3a2b',
});

Python

# The SDK auto-generates Idempotency-Key on every retryable request.
# To supply your own:
client.nature.subjects.create(
    ...,
    idempotency_key="8e9c4f2a-3b1d-4e5f-9a8b-7c6d5e4f3a2b",
)

---

Replayed responses

When a replayed response is returned, the API sets:

Idempotency-Key: 8e9c4f2a-3b1d-4e5f-9a8b-7c6d5e4f3a2b
X-Idempotency-Replayed: true

Check X-Idempotency-Replayed if you need to distinguish between a fresh response and a replay.

---

Errors

Code	Status	Cause
idempotency_key_in_use	409	A request with this key is currently in-flight. Wait for it to complete before retrying.

---

Key generation rules

• Use a UUIDv4 or other high-entropy random string
• Never use PII (email, name, user ID) as the key
• Use a new key per distinct operation — reusing a key from a different operation type returns the original response, not the new one
• Max length: 255 characters