---
title: "Idempotent requests"
description: "Retry safely after a timeout with an idempotency key, so nothing happens twice."
url: "https://nov18-prod-sg.movespot.fyi/guides/idempotency"
image: "https://nov18-prod-sg.movespot.fyi/_og/d/c_Ocean.takumi,title_Idempotent+requests,description_~UmV0cnkgc2FmZWx5IGFmdGVyIGEgdGltZW91dCB3aXRoIGFuIGlkZW1wb3RlbmN5IGtleSwgc28gbm90aGluZyBoYXBwZW5zIHR3aWNlLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiNDQjUzMjQifX19,p_Ii9ndWlkZXMvaWRlbXBvdGVuY3ki,s_lY_i0gptG40Trqcd.png"
---

# Idempotent requests

Retry safely after a timeout with an idempotency key, so nothing happens twice.

## [Why you need this](#why-you-need-this)

Networks fail in the worst possible moment. You send a request to create an order, the connection times out, and you don't know whether the server processed it. If you retry blindly, you risk creating the same order twice.

An idempotency key solves this. You generate a unique string, send it with the request, and the API guarantees that the same key always returns the same result, no matter how many times you retry.

## [Send an idempotency key](#send-an-idempotency-key)

Add the `Idempotency-Key` header to any request that creates or changes data:

```bash
curl "https://api.example.com/v1/orders" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: ord-2024-10-01-001" \
  -H "Content-Type: application/json" \
  -d '{"total": 42.50, "currency": "USD"}'
```

If the first attempt succeeded but the response was lost, the retry returns the original response instead of creating a duplicate.

## [The rules](#the-rules)

-   Keys are remembered for **24 hours**. After that, a reused key is treated as a new request.
-   Reusing a key with a **different request body** returns a `409 Conflict`. That means you have a bug worth investigating, not a transient failure.
-   Generate a **new key for every logical operation**, not for every attempt. One key per user action, reused across retries.
-   Use UUIDs or a random string, so keys from different clients never collide.

## [What to do on a timeout](#what-to-do-on-a-timeout)

1.  Retry the exact same request with the exact same key.
2.  If you get `409 Conflict`, compare the stored response. Something changed between attempts.
3.  Log the final `request_id` either way, so support can trace it.

## [Next steps](#next-steps)

### Errors

Understand error responses and decide which requests to retry.

<https://nov18-prod-sg.movespot.fyi/guides/errors>

### Make your first request

Walk through a complete request and response, headers to status codes.

<https://nov18-prod-sg.movespot.fyi/guides/first-request>

### Webhooks

Get notified when resources change instead of polling.

<https://nov18-prod-sg.movespot.fyi/guides/webhooks>