Deployments.ai Docs

Idempotency

Make retries safe with idempotency keys: which operations need one, key rules, and replay behavior.

An idempotency key lets you retry a mutation without doing the work twice. Send a unique key in the idempotency-key header. If the request fails in a way that leaves you unsure whether it ran, send the same request with the same key. The platform runs it once and returns the original result to every retry.

Which operations take a key

Each operation declares one of four idempotency modes. Its reference page shows whether the header is required.

ModeHeaderOperations
RequiredMust be presentMost create, update, archive, and action operations, including tenancy, agents, run submission, and email.
OptionalAccepted but not requiredMemory operations other than reads.
Required or bodyRequired unless the body has a stable fireKeyFiring a schedule or a heartbeat manually.
NoneIgnoredReads, and some mutations, such as accepting an invitation, canceling or retrying a run, and creating a thread.

A request that omits a required key fails before it does any work.

Key rules

The allowed length depends on the authentication scheme of the operation.

OperationsKey lengthOther rules
Runtime, automation, and workflow execution operations (API key or platform access token)1 to 256 UTF-8 bytesNo leading or trailing whitespace. No control characters.
Memory and Brains operations (tenantJwt)1 to 500 UTF-8 bytes
All other operations1 to 512 characters

Use a fresh random value, such as a UUID, for each new piece of work. Store the key with the work item so a retry after a crash reuses it.

What a retry returns

SituationResult
Same key, same request, first request finishedThe original response. No work runs again.
Same key, same request, first request still runningStatus 409 with code idempotency_in_progress. Wait and retry.
Same key, different requestStatus 409 with code idempotency_conflict.
Same key, a tenancy or agent operation that failed with an errorThe platform releases the key, so a retry runs the operation again.

"Same request" means the same operation, the same target resource, the same tenant scope, and the same body. Changing any of them with an old key is a conflict.

Scope and retention

The scope of a key depends on the operation.

  • For tenancy and agent operations, the platform scopes each key to the caller. It keeps a completed key for 24 hours. After that, the same key starts a new request.
  • For run submissions, the platform scopes each key to the organization, project, environment, and workspace. A run submission key never expires. Reusing it always returns the original run or a conflict.

A run submission replay returns the original thread, run, and message with created set to false. A replay succeeds even when a spend budget would now refuse a new run, because the run was already admitted.

Send a key

The CLI generates a key for each command that sends one. The run message publication commands require --idempotency-key. Pin your own key with --idempotency-key when you need to resume work after a crash:

deployments chat --agent $AGENT_DEPLOYMENT_ID --message "Summarize the release notes" --idempotency-key "$WORK_ITEM_ID"

Reference

On this page