> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amlok.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency and concurrency

> Retry intended actions safely and protect mutable configuration from stale writes.

## Idempotency for POST commands

Every POST operation requires an `Idempotency-Key`. Generate it once for one intended action, store it with the payload, and reuse both for retries.

```http theme={null}
Idempotency-Key: onboarding-connection-1001
```

The deduplication scope is **institution + workspace + environment + operation + key**, with the resolved target path and intended payload validated in its fingerprint, with **24-hour retention**. An identical replay returns the original result; a different intended payload with the same key returns `409 idempotency_conflict`.

| Situation | Client behavior |
| - | - |
| Network timeout after POST | Keep the same key and identical payload; the command may already have been accepted. |
| Transient 429/503 | Respect the retry delay and reuse the same key for that action. |
| 409 conflicting payload | Reconcile the original action. Use a new key only for a genuinely new intended action. |
| Retry beyond the retention window | Reconcile the existing resource/job before creating a new action. |
| Multipart upload | Reuse the same file bytes and logical fields. Keep the request content unchanged when retrying. |

After full-response replay expires, a retained key returns `409 idempotency_result_expired` without executing again. Durable receipts remain until workspace deletion. [Look up the original accepted request](https://docs.amlok.io/api-reference/request-recovery.md) before taking another action.

Never generate a new idempotency key on every automatic retry. Do not assume a command is safe to replay indefinitely after deduplication retention expires.

## Optimistic concurrency for PATCH

Read the current [monitor](https://docs.amlok.io/api-reference/endpoints/risk/retrieve-monitor.md), retain the quoted `ETag`, and send it in `If-Match`. The PATCH body changes only explicitly supplied fields.

```http theme={null}
PATCH /v1/monitors/mon_example
Authorization: Bearer <AMLOK_API_KEY>
Content-Type: application/json
If-Match: "3"

{"status":"paused"}
```

In the synthetic success example the new record version is `4` and the ETag is `"4"`. A stale precondition returns `412 version_conflict`. Re-read, compare, and decide whether the change is still intended; do not blindly overwrite the newer record.

The PATCH schemas reject empty bodies, unknown properties, and null clearing. Omit fields you do not intend to change.

A pre-execution `402 insufficient_credits` rejection does not reserve an accepted operation or charge credits. After funding, retry the same intended request with the same key.

See [errors](https://docs.amlok.io/api-reference/errors.md) and [asynchronous jobs](https://docs.amlok.io/api-reference/async-jobs.md) for recovery behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.