Skip to main content

Idempotency

A request that times out may have run or not. To retry a write safely, send an Idempotency-Key header with a unique value, such as a UUID, on any POST, PUT, PATCH or DELETE, and send the same value when you retry it. MCP write tools take the same value as their idempotencyKey argument.

curl -X POST https://api.rollstack.com/public/v1/reports \
  -H "Authorization: Bearer rsk_..." \
  -H "Idempotency-Key: 6f1c2a4e-9b7d-4e2f-8a3c-1d5e7f9b0a2c" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly sales"}'
  • The first request with a key runs, and its response is kept for 24 hours. A retry with the same key and the same request answers that response, with its status, and runs nothing.
  • Keys belong to the API key and the endpoint, so another key or endpoint never sees them. A tool call and a REST request to the same endpoint share them.
  • A retry with the same key but a different body, path or query answers 422 idempotency-key-reused. Use a new key for a new request.
  • A retry while the first request is still running answers 409 idempotency-key-in-progress: retry it later with the same key. A request that stopped before it answered keeps answering 409 until its key expires, so check whether it took effect before you send it again with a new key.
  • A request that fails, such as with a 4xx or 5xx, keeps nothing, so retry it with the same key.
  • When keys can't be checked, a request with one answers 503 idempotency-unavailable and runs nothing.
  • Without the header, a request runs every time it is sent. GET requests ignore it.