# Idempotency and retries

> Make writes safe to retry with Idempotency-Key.

Networks fail after a request arrives and before its answer does. To retry a write without doing it twice, send an `Idempotency-Key` header with a value unique to that request — a UUID:

```bash
curl -X POST https://api.bymundi.com/v1/trips \
  -H "Authorization: Bearer $BYMUNDI_KEY" \
  -H "Idempotency-Key: 2f1c6c1e-3b1a-4c1e-9d3f-5a7e0b9c2d11" \
  -H "Content-Type: application/json" \
  -d '{"title":"Kyoto in spring"}'
```

## Rules

- Every write (`POST`, `PATCH`, `DELETE`) accepts it; reads ignore it.
- The first answer is stored for **24 hours**. Repeating the same request with the same key replays that answer — same status, same body — without doing anything again.
- The same key with a **different** request answers [`422 idempotency_key_reused`](https://api.bymundi.com/problems/idempotency_key_reused.md).
- While the first request is still running, a repeat answers [`409 request_in_progress`](https://api.bymundi.com/problems/request_in_progress.md). Wait and retry.
- Keys are 1–255 characters and scoped to your API key.

## A retry loop

Retry on network errors, `429`, `500` and `503`, with exponential backoff (1 s, 2 s, 4 s…) and the **same** `Idempotency-Key`. On `429`, wait at least `Retry-After` seconds. Do not retry other 4xx answers: they will not change.

Over MCP, tools that are safe to repeat say so with `idempotentHint`.