Make agent retries safe

Agents retry. A request times out, a connection drops, a step looks like it failed — so the agent tries again. For a write, a blind retry can mean the same records inserted twice. An idempotency key makes that safe.

The problem, concretely

Your agent asks Search Stack to insert ten products. The insert actually succeeds, but the response is lost on the way back. The agent, seeing no confirmation, sends the same insert again. Without protection you now have twenty records — ten of them duplicates. This is exactly the failure mode that makes people nervous about letting an agent write.

The fix: name the attempt

Send an idempotency key — any unique string identifying this attempt — in a header. The first request does the work and Search Stack remembers the key; a retry carrying the same key returns the original result instead of doing the work again. Same request, same key, one effect.

POST https://api.searchstack.dev/search-result/Demo/products/with-fields
X-API-Key: {your key}
Idempotency-Key: load-products-2026-07-17-batch-1
Content-Type: application/json

[ { "name": "Trail Runner 2", "brand": "Vireo", "price": 119 }, … ]

Retry that request — same Idempotency-Key — and the second call is a no-op that returns the first call's outcome. Change the key and it's treated as a new, intentional insert. It's the difference between "do this" and "make sure this happened exactly once".

Why it matters for agents especially

The key travels the same whether you call the API directly or the agent calls it over MCP — the header is forwarded through, so an agent's writes get the same exactly-once guarantee your own code would. That's what turns "an agent can write to my data" from a worry into something routine: even a nervous agent that retries three times leaves your list in the state it should be.

Go deeper: Write operations and safe retries in the reference.