Idempotency and safe retries
Retry mutations without creating a second logical operation.
Mutation endpoint pages declare whether idempotency-key is required. Reads reject this header with 400 IDEMPOTENCY_KEY_NOT_ALLOWED.
For one logical write, generate one random key and keep it with the exact request until the outcome is known. Accepted formats are a canonical lowercase UUIDv4 or an unpadded canonical base64url value with 128 or 256 bits of entropy.
Idempotency-Key: <random-uuid-v4>A retry must use the same method, path, context, preconditions, query, body, and key. Authentication and authorization are checked again before a stored result is replayed. Results are retained for at least 24 hours according to the operation's policy.
Recover from an unknown result
| Outcome | Action |
|---|---|
| Lost response, network failure, or retryable availability error | Retry the exact request with its original key and bounded backoff. |
409 IDEMPOTENCY_REQUEST_IN_PROGRESS | Respect Retry-After, then retry the original request and key. |
409 IDEMPOTENCY_KEY_CONFLICT | The key was reused for different input. Reconcile the prior outcome; use a new key only for a new intended write. |
| Revision or state conflict | Read current state and reconcile it before creating a new logical request with a new key. |
Some operations require a revision or explicit confirmation in addition to an idempotency key. The key does not bypass those checks.
Secret-returning operations
Token minting and other selected secret-returning operations also require X-NeatLogs-Secret-Replay-Key: 32 random bytes encoded as unpadded base64url. Keep that key alongside the original request so a lost response can be recovered. The endpoint's schema describes the encrypted result envelope; it is not a plaintext token response.
Use the CLI's supported secret-handling commands where available, and deliver resulting secrets directly to protected storage. Never print a replay key or token into logs.
CLI writes
Supported mutation commands accept --idempotency-key and can generate a key when omitted. For ordinary writes that do not return secrets, preserve a reported recovery key and repeat the original command with that key and identical input.
Secret-returning CLI commands keep their secret replay key only during that invocation. They can retry while running, but starting a new command generates a new replay key. If the process exits before its token result is safely stored, reconcile the token inventory and revoke only a token confirmed to have been created by that attempt before minting a replacement. Do not try to recover the old secret by rerunning the command with only its idempotency key. A direct API client can recover a secret response only when it has preserved both original keys and the exact request.
neatlogs projects update --name 'Support agent' \
--idempotency-key '<random-uuid-v4>' --jsonThis example performs a write and requires the corresponding scope, project role, and operation availability. Inspect the command reference before running it.