Idempotency

Networks fail. A request can time out after Parasend has already sent the delivery, and a plain retry would send it twice. To make retries safe, every POST carries an Idempotency-Key header: a value you choose, unique for each new action.

curl -X POST "https://api.parasend.com/v1/deliveries" \
  -H "Authorization: Bearer $PARASEND_KEY" \
  -H "Idempotency-Key: 5f0c6a1e-8a3b-4d2e-9c71-2b4f6e8d0a13" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

#How it works

• First request with a key: Parasend does the work and keeps the answer for 24 hours.
• The same key and the same body within 24 hours: Parasend does nothing new and returns the stored answer, with the header Idempotent-Replayed: true.
• The same key with a different body: 409 idempotency_key_reused. A key belongs to one request.
• No key on a POST: 400 idempotency_key_missing.

Only successful answers are kept. If the first attempt failed with an error, a retry with the same key runs again, so you can fix a problem and retry.

Keys are kept per account and mode, and per method and path: your keys never meet another customer's, and a key used in test mode does not affect live mode.

#Choosing keys

• 1 to 255 characters of A–Z, a–z, 0–9, _ and -. Anything else answers 400 idempotency_key_invalid.
• A UUID works well. Better still, derive the key from your own record, such as invoice-2026-114-notice, so a restart of your system cannot send the same notice twice.
• Make a new key for each new action, and reuse it only to retry that action.

Only POST needs a key. GET, PATCH and DELETE requests carry none: repeating one leaves the same result. Our code examples send a key on every POST.