Retries and concurrency

Use each resource’s current ETag in If-Match for conditional edits. A missing required condition returns 428, a stale condition 412, and malformed input 422. Read the current representation before deciding whether to apply a conflicting edit. A Live event cursor is not an ETag.

Duplicate-sensitive creation supports optional Idempotency-Key: organization and personal Live creation, queue insertion, presentation creation, asset upload, portable import and export jobs. Use one random UUID per intended creation. Retain it and the original request input across retries.

For this personal Live example, replace the account UUID in the URL with the personal_account_id returned by GET https://api.bibleit.app/v1/me. Creating a Live requires live.create.

curl \
  --header "Authorization: Bearer <token>" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 806405fe-26fa-43e1-95e8-bf95945b29e8' \
  --data '{"name":"Friday Live"}' \
  "https://api.bibleit.app/v1/accounts/00000000-0000-4000-8000-000000000001/lives"

Keys are case-sensitive, 1–128 ASCII letters, digits, ., _, : or -. Successful results are retained for 24 hours, scoped to the account, concrete method/path and credential principal. Service-secret rotation preserves the principal; delegated access rotation preserves its grant. Different credentials cannot retrieve each other’s results.

Payload, query, Content-Type and original If-Match must match. JSON object order is ignored; queue defaults and reference casing are normalized. Raw bytes are hashed exactly. Changed input returns 409 idempotency_conflict. Concurrent requests serialize; retry-lock contention can return 409 idempotency_in_progress, and bounded dependency waits may return 503.

The resource and successful retry result commit together. A replay rechecks current access and returns the historical creation result without consuming another resource quota. It does not recreate deleted resources or renew expired jobs. Replayed queue insertion accepts its original If-Match, even after later Live changes. Read current state before subsequent edits. Failed creations leave no replay record. After expiry, the same key is treated as new.

Credential issuance/rotation and one-use export downloads reject idempotency keys. Issued secrets cannot be recovered. OAuth exchanges retain their single-use rules. Never blindly retry an ambiguous mutation or exchange. Every retry uses normal admission budgets; honor Retry-After and use bounded backoff.