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.
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#
| Case | Answer |
|---|---|
| First request with this key | The request runs. Yaqeen keeps the answer for 24 hours. |
| Same key, same body | The first answer again, with the header Idempotent-Replayed: true. Nothing runs. |
| Same key, different body | 422 idempotency_key_reused. Use a new key for the new request. |
| Same key while the first request is still running | 409 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:
| Result | Meaning |
|---|---|
done | The decision ran. |
pending_approval | The hold needs a second person first. |
failed | The 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_progressagain 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#
- Handle errors: which errors you can retry.
- Hold statuses: why a second decision on the same hold can fail.
- Errors: every code and its fix.