Idempotency - Chataigne Docs

Resource-creating POST requests require an Idempotency-Key header. The key lets you safely retry a request after a timeout or connection failure without creating the same resource twice.

curl https://server.chataigne.ai/v1/locations/loc_r8v4n2c6tz/special_closings \
  -X POST \
  -H "x-api-key: $CHATAIGNE_API_KEY" \
  -H "Idempotency-Key: 6f1d3b8a-2c47-4e90-9a1b-0d2f7c5e1234" \
  -H "Content-Type: application/json" \
  -d '{
    "starts_at": "2026-12-24T23:00:00Z",
    "ends_at": "2026-12-25T23:00:00Z",
    "reason": "Christmas Day"
  }'

Generate keys

Use a new unpredictable value, such as a UUID v4, for each logical creation request. Store it with the operation until you receive a definitive response.

Node.js

import { randomUUID } from 'node:crypto';

const idempotencyKey = randomUUID();

Retry rules

Retry the same operation with the same key and exactly the same request body.
A completed replay returns the original response and includes Idempotent-Replayed: true.
Reusing a key with a different body returns 409 idempotency_error.
Sending a concurrent duplicate while the first request is still running returns 409 conflict_error; wait briefly, then retry the same request.
Keys are retained for 24 hours.

Do not generate a new idempotency key for a retry. A new key represents a new creation request and can create a duplicate resource.

PATCH, PUT, GET, and DELETE requests do not require this header. See Errors for bounded retry guidance.

​Generate keys

​Retry rules

Generate keys

Retry rules