{
  "object": "doc",
  "title": "How do I retry a Cartroute call safely?",
  "description": "Idempotency-Key replays, which errors to retry, and backoff.",
  "section": "Concepts",
  "url": "https://cart-route.com/docs/idempotency",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs/rate-limits",
  "next": "https://cart-route.com/docs/pagination",
  "text": "Send an `Idempotency-Key` header on metered calls. If the same key is used again for the same operation within 24 hours, Cartroute returns the first response unchanged, with `idempotent_replay: true`, and charges nothing. That makes it safe to retry after a timeout without paying twice.\n\n## How do I use an idempotency key?\n\n```\ncurl \"https://cart-route.com/api/v1/search?q=robot+vacuum\" \\\n  -H \"Authorization: Bearer $CARTROUTE_API_KEY\" \\\n  -H \"Idempotency-Key: 4b1d7c1e-3f2a-4a4e-9a57-1b1a2f6c0e91\"\n```\n\nUse a fresh random value (a UUID) per logical request, and reuse it only when retrying that same request. Keys are scoped to your account and the operation, up to 200 characters.\n\n## Which failures should be retried?\n\n| Outcome | Retry? | How |\n\n| Network error or timeout | Yes | Same request, same `Idempotency-Key`. |\n\n| `429 rate_limited` | Yes | After `Retry-After` seconds. |\n\n| `500 internal_error`, `502`, `503`, `504` | Yes | Exponential backoff: 1 s, 2 s, 4 s, up to 3 attempts. |\n\n| `401`, `402`, `403`, `404` | No | The answer will not change. |\n\n| `422` | Only after fixing | Change the parameter named in `param`. |\n\n## What does a replayed response look like?\n\nIdentical to the original body, plus `\"idempotent_replay\": true` and `\"credits\": {\"charged\": 0, \"remaining\": ...}` showing the current balance.\n\n## Does the MCP server support idempotency?\n\nNot per call. MCP clients do not send an equivalent key, so each successful `tools/call` is charged. Agents that need retry-safety for expensive loops should call the REST API."
}