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.

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 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, retain the quoted ETag, and send it in If-Match. The PATCH body changes only explicitly supplied fields.

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 and asynchronous jobs for recovery behavior.