Idempotency and retries

Agents retry. A tool call times out, a network hiccup drops a response, an agent loop repeats a step—and without protection, each retry starts fresh billable work. Pass an idempotency_key and Titan recognizes the repeat, returning the original run instead.

How it works

Keys are scoped to your user and the capability, so the same key used for a search and a fetch does not collide. Entries are retained for 24 hours.

Which tools accept it

titan_search, titan_fetch, titan_crawl, and titan_run_template—every tool that starts billable work. titan_get_run and titan_list_templates do not need it. They are already free and side-effect-free.

Using a key

{
  "urls": ["https://example.com/pricing"],
  "format": "markdown",
  "idempotency_key": "pricing-check-2026-07-27"
}

Choose keys that identify the work, not the attempt:

Good	Why
`pricing-check-2026-07-27`	Same logical job on the same day deduplicates
`research-session-8f3a-step-2`	Stable across retries within one agent run
A hash of the request parameters	Identical requests collapse automatically

Avoid	Why
A fresh UUID per attempt	Never matches, so it protects nothing
A timestamp to the millisecond	Same as above
A constant like `"key"`	Collapses unrelated work into one stale run

Replay warnings

A deduplicated call tells you so, in warnings:

Code	Meaning
`idempotency_active`	The original run is still in flight. You received its `run_id`; poll it.
`idempotency_replay`	The original run already finished. You received its result.

Treat both as success. The work is happening or has happened—your retry did the right thing by not duplicating it.

{
  "run_id": "3c7d1a92-6f48-4b25-9e03-7d1a4c8b2f65",
  "status": "running",
  "warnings": [
    { "code": "idempotency_active", "message": "a run for this idempotency key is already in progress" }
  ]
}

Retrying without a key

If you did not pass a key and a call fails, decide by error code before retrying.

Error	Retryable	Guidance
`backend_unavailable`	Yes	Retry with backoff
`timeout`	Yes	Retry, or poll if you have a `run_id`
`provider_rate_limited`	Yes	Back off longer, or switch `search_provider`
`provider_failed`	Sometimes	Retry once; if it persists, try another provider
`invalid_request`	No	Fix the parameters
`unauthorized` / `forbidden`	No	Fix the key or its scopes
`insufficient_credits`	No	Top up, or request less work
`limit_exceeded`	No	Lower the limit
`unsafe_url`	No	Use a different URL
`template_not_found`	No	Use an allowlisted slug

Every error body carries a retryable boolean, so an agent can branch on it without hardcoding this table.

Do not retry a run that is still going

The most expensive mistake is treating a timeout as a failure. When a tool returns running or queued with a next_step warning, the run is alive. Re-issuing the call starts a second run for the same work, and you pay for both.

Wrong:  titan_fetch(...) → running → titan_fetch(...) again
Right:  titan_fetch(...) → running → titan_get_run(run_id)

Retry with backoff

async function callWithRetry(client, name, args, maxAttempts = 3) {
  const key = `${name}-${hashOf(args)}`;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const result = await client.callTool({
      name,
      arguments: { ...args, idempotency_key: key },
    });

    if (!result.isError) return result;

    const error = JSON.parse(result.content[0].text);
    if (!error.retryable || attempt === maxAttempts) throw new Error(error.message);

    await sleep(1000 * 2 ** (attempt - 1));
  }
}

The stable idempotency_key means even if a “failed” call actually started a run, the retry joins it rather than duplicating it.

Next steps

Errors and warnings — every code and its meaning
Runs and results — polling instead of retrying
Credits and usage — why duplicate runs cost real money

Get started

Tool reference

How it works

Integration examples

How it works

Which tools accept it

Using a key

Replay warnings

Retrying without a key

Do not retry a run that is still going

Retry with backoff

Next steps

​How it works

​Which tools accept it

​Using a key

​Replay warnings

​Retrying without a key

​Do not retry a run that is still going

​Retry with backoff

​Next steps

How it works

Which tools accept it

Using a key

Replay warnings

Retrying without a key

Do not retry a run that is still going

Retry with backoff

Next steps