A network error does not tell you whether the server acted. Retrying a POST blindly risks doing the work twice — a second collection created, a second photo added. Send an Idempotency-Key and the retry is free: Pexafy replays the first response instead of running the request again. This applies to POST requests only. GET and DELETE are already safe to repeat, so they ignore the header.

​
Using it

Generate a unique key per logical operation — a UUID is the usual choice — and send it with the request: 
curl -X POST "https://api.pexafy.com/api/v1/collections" \
  -H "x-api-key: $PEXAFY_API_KEY" \
  -H "Idempotency-Key: 7d1f0c2e-3b64-4f8a-9c11-2ad5e6f80b93" \
  -H "Content-Type: application/json" \
  -d '{"name": "Autumn campaign"}'
Retry the exact same call and you get the same body and the same status code back, plus a header telling you it was a replay rather than a fresh action: 
X-Idempotent-Replay: true

​
Rules

RuleDetail
ScopePOST only. Other methods ignore the header.
Key formatUp to 128 characters, letters, digits, - and _. Anything else is rejected with 400 INVALID_IDEMPOTENCY_KEY.
Retention24 hours. After that the key is forgotten and the same request would act again.
What is storedSuccessful responses only (2xx). A failed request is not remembered, so you can retry it and actually get through.
ReuseA key identifies one operation. Reusing it for a different request returns the first response, not the new one — so never reuse a key across operations.
Keys are stored per key value, not per endpoint. Generate a fresh one for each operation you want to be able to retry.

​
When to bother

Use it whenever a failed call would be expensive to repeat — creating a collection, adding photos in bulk from a job that may be retried by your queue. For plain searches it adds nothing: GET /search/photos is already safe to repeat as often as you like.