Idempotency
Dashboard

Idempotency

Avoid duplicate objects on network failures by sending an Idempotency-Key on POST requests.

The problem

You POST to create an invoice, then the connection drops before you see the response. Was it created or not? Without idempotency you have to guess — retrying may create a duplicate.

The solution

Give every POST a unique Idempotency-Key header, for example a UUID you generate:

bash
curl -sS -X POST https://api.appficient.nl/v1/invoices \
  -H "Authorization: Bearer apf_your_key_here" \
  -H "Idempotency-Key: 5f3c1a9e-8b2d-4c7e-9f1a-2d3b4c5e6f7a" \
  -H "Content-Type: application/json" \
  -d '{ "client_guid": "...", "title": "..." }'

Retrying the same request with the same key returns the same response and creates nothing twice. Replays include X-Idempotent-Replay: true.

Rules

  • Applies to POST endpoints that accept the header. GET, PATCH and DELETE are already safe to retry.
  • One key per logical action. New action, new key.
  • Keys remain valid for 24 hours (cached).