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 can be any 1 to 255 characters, and a UUID is ideal. Use a new key 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.
• The header needs an API token. Some POSTs, such as checking an AI provider, trying a model or checking for updates, create nothing and ignore the header.