Idempotency

Network failures happen mid-request. To retry a create without risking a duplicate, send an Idempotency-Key header on POST /public/v1/posts and POST /public/v1/media:

curl -X POST https://api.mouve.it/public/v1/posts \
  -H "Authorization: Bearer $MOUVE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f2b6c1e-8a4d-4e9b-9c7a-5d0e1f2a3b4c" \
  -d '{"text": "…", "audience": "everyone"}'

Semantics

• Key format: 1–255 visible ASCII characters. A UUIDv4 per logical operation is the recommended choice. Malformed keys are a 400 INVALID_IDEMPOTENCY_KEY.
• First request with a key executes normally and its response is stored.
• Retries with the same key replay the stored response verbatim, marked with the Idempotency-Replayed: true header. Both successes and deterministic client errors (4xx) are replayed; a 5xx clears the key so your retry executes for real.
• Same key, different body → 422 IDEMPOTENCY_BODY_MISMATCH. A key names one operation; never reuse it for another payload.
• Concurrent duplicate (first request still executing) → 409 IDEMPOTENCY_IN_FLIGHT with Retry-After: 2. Retry with the same key.
• Scope: keys are namespaced per user, per credential, and per endpoint. Two of your tokens using the same key do not collide, and a key used on /posts cannot replay a /media response.
• Lifetime: 12 hours. After that the key is forgotten and reuse executes a fresh request. Do not reuse yesterday's keys for today's scheduled repeats — mint a new key per logical operation.

The honest fine print

Idempotency protects against duplicate effects to the same guarantee level as other major APIs: in the narrow window where the operation committed but its response was not yet stored, a crash followed by a retry after the lease expires can execute the operation a second time. This is rare, bounded to one duplicate, and stated here so you can decide whether to add your own reconciliation for critical flows.

Requests without an Idempotency-Key have no retry protection at all — sending the header on every create is the strongly recommended default.