baleybots
← All guides
An API job moving through request, queue, execution, retry, and completion states
API operations

· Baleybots

Use idempotency keys when starting AI work

A timeout does not tell you whether the server started the work. Retrying without an identity can create a second run, duplicate costs, or repeated destination writes.

Name the logical request

Generate an idempotency key for one intended operation and reuse it when retrying that same request. Do not generate a fresh key on every HTTP attempt. Also do not reuse one key for different documents or configurations. The server needs to distinguish a retry from a conflicting attempt to redefine the operation.

Workflow at a glanceName the logical requestUse this sequence as a small fixture before you scale the work.
  1. 1Persist the key with your job record…Persist the key with your job record before the first request.
  2. 2Reuse the key and the same payload…Reuse the key and the same payload after an uncertain response.
  3. 3Treat a conflicting payload as a new…Treat a conflicting payload as a new operation or a client bug.

Try it on a small example

  1. Persist the key with your job record before the first request.
  2. Reuse the key and the same payload after an uncertain response.
  3. Treat a conflicting payload as a new operation or a client bug.

What to verify

Baleybots callable runtime requests validate Idempotency-Key and return an idempotency_conflict for a different runtime request using the same key. That protects the supported start operation; it does not automatically make every downstream system idempotent. Give destination writes stable record identities too. Test a lost response followed by a retry and verify both run identity and external side effects.

Product details checked against the Public API reference on October 4, 2026. These guides describe documented behavior; availability depends on your account and the deployed service. Baleybots is in invite-only beta.