Idempotency & retries

One key per intended call

Every create request requires an Idempotency-Key header. Generate it once and save it with the complete request before making the network call.

Authorization: Bearer <API_KEY>\nIdempotency-Key: 2dc65313-6bd6-41e8-b63e-6d932f1da807\nContent-Type: application/json

The UUID above is illustrative. Generate your own value for each new call. Unlike the secret API key, it is a request identifier and does not grant access. Save the API origin, complete payload, idempotency key, and returned call ID together.

The key is scoped to your Agent Project. Sending the same request with the same key returns the original call. Creating a new key represents a new intended call.

Replaying an existing failed or cancelled call returns that same record; it does not restart it. Replays still require valid authentication and current access permissions.

Recover an uncertain request

A timeout, disconnected connection, or server error can occur after a call was created. A missing response is not proof that nothing happened.

1. Keep the original request payload and idempotency key.
2. If you received a call ID, use it to sync the existing call.
3. If no ID was returned, replay the identical create request with the same key, API origin, and Agent Project.
4. Use the returned call ID to continue following that call.

For cURL, restore the original key before running the same create command:

export IDEMPOTENCY_KEY="PASTE_THE_ORIGINAL_IDEMPOTENCY_KEY"

For the Python snippet, paste that key when prompted instead of pressing Enter. For the downloaded self-call script, supply --idempotency-key YOUR_ORIGINAL_KEY with the same phone number and base URL. Do not switch between the script’s task and the JSON-file task when recovering; their payloads differ.

Handle conflicts

409 idempotency_conflict means the key was already used with different call details. Restore the original payload to recover the existing call. Use a new key only when you intentionally want another call.

Task text, destination, context, protected_context, constraints, success criteria, result schema, and duration are all part of the frozen request. Keep them unchanged for recovery.