Idempotency

If a POST times out, you can't tell whether it worked. Send an Idempotency-Key header with it, and retry with the same key: Nifty creates the record once and answers the retry with the first response.

key=$(uuidgen)
curl -X POST "$NIFTY_URL/api/v1/categories" \
  -H "Authorization: Bearer $NIFTY_TOKEN" \
  -H "Idempotency-Key: $key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Travel", "color": "blue"}'

A replayed response has the same status and body as the first, plus Idempotent-Replayed: true.

The rules

• The key is any 1 to 255 characters; a UUID is ideal. Use a new one for each new record.
• Nifty remembers a key for 24 hours, for your token, the method and the path.
• Only successes are remembered: after an error, fix it and retry with the same key.
• The same key with a different body gets 422 idempotency_key_reused.
• A retry while the first request is still running gets 409 idempotency_key_in_use: wait and try again.
• It needs an API token. A few POSTs create nothing (checking an AI provider, trying a model, checking for updates) and ignore the header.