YaqeenDocs
Back to Yaqeen

How-to guide

Safe retries

Use an Idempotency-Key header so a retried decision runs only once.

This guide shows how to resend a decision without deciding twice. A network can fail after Yaqeen has acted, and then you do not know if the decision ran. You need a reviewer or admin account, or a key with the decide scope.

Where it works#

Yaqeen reads the Idempotency-Key header on three endpoints only:

  • POST /api/v1/holds/{id}/decision/
  • POST /api/v1/holds/bulk-decision/
  • POST /api/v1/ingest/feed/

On any other endpoint the header is ignored.

Send a key#

The key is 8 to 128 letters, digits, - or _. Use a new key for each decision you intend to make, such as one UUID per decision. Keep the same key when you resend that decision.

bash
curl -X POST https://api.example.test/api/v1/holds/$ID/decision/ \
  -H "Authorization: Bearer yq_live_..." \
  -H "Idempotency-Key: 5f0c2a-approve-001" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approve"}'

A key that does not match the format gets 400 bad_idempotency_key.

What you get back#

CaseAnswer
First request with this keyThe request runs. Yaqeen keeps the answer for 24 hours.
Same key, same bodyThe first answer again, with the header Idempotent-Replayed: true. Nothing runs.
Same key, different body422 idempotency_key_reused. Use a new key for the new request.
Same key while the first request is still running409 in_progress. Wait a moment and send it again.

What is stored#

Yaqeen keeps the first answer for any status below 500. That includes errors such as 409 bad_transition, so a replay returns the same error. An answer with status 500 or higher is not kept, so you can send the same key again and the request runs again.

A key is tied to the signed-in account, the HTTP method and the path. The same key sent to a different hold's address is a separate request. Yaqeen compares the raw body, so a body with the same fields in a different order counts as different.

Bulk decisions#

POST /api/v1/holds/bulk-decision/ takes 1 to 50 hold ids, one decision and an optional note. A repeated id counts once. Each hold gets its own result:

ResultMeaning
doneThe decision ran.
pending_approvalThe hold needs a second person first.
failedThe decision did not run. The result has a code and a message.

The response also counts each kind. One failed hold does not undo the others.

If it does not work#

  • You get 422 idempotency_key_reused: you changed the body. Send the original body with the same key, or use a new key.
  • You get 409 in_progress again and again: the first request may still be running. Wait about a minute. Yaqeen treats a request as running for at most 60 seconds.

Next steps#

Up Down to moveEnter to openEsc to close