Skip to content

DocsDevelopers

Idempotency

Retry POST requests safely with an Idempotency-Key.

Networks fail. Send an Idempotency-Key with a POST and you can retry it without making (or paying for) the work twice.

How it works#

curl
curl https://www.loudscene.com/api/v1/videos/<id>/renders \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5c0b6f7e-8a1d-4c7e-9b2f-3a4d5e6f7a8b" \
  -d '{"format":"9:16","resolution":1080}'
  • The key is 1 to 255 printable characters without spaces. A UUID per logical operation works well.
  • The first answer (anything below 500) is stored for 24 hours. A retry with the same key and the same body gets that answer again, with the header Idempotent-Replayed: true.
  • The same key with a different body is refused with 422 idempotency_mismatch.
  • While the first request is still running, a retry gets 409 conflict with Retry-After: 1.
  • A server error (5xx) is not stored, so retrying with the same key runs the request again.

Keys are scoped to your workspace. GET and PATCH requests do not need them.