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:

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.
• While the first request is still running, a repeat answers 409 request_in_progress. 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.