Idempotency

How it works

Send an Idempotency-Key header with a unique string (UUID recommended) on every POST. If the same key is sent again with the same request body, the API replays the original response instead of creating a duplicate. Omit the header and the request is rejected with a 400 IDEMPOTENCY_KEY_REQUIRED.

curl -X POST \
  -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"name": "Saturday 5K", "type": "race", "date": "2026-03-15", "slug": "saturday-5k"}' \
  https://api.intervals.run/events

Conflict detection

Reuse the same key with a different request body and the API returns a 409 CONFLICT — this is a client bug, so don't retry. If a request with the same key is still in flight, you get a 409 IDEMPOTENCY_KEY_IN_PROGRESS instead, which is safe to retry once the first request finishes.

{
  "error": {
    "code": "CONFLICT",
    "message": "Idempotency key already used with a different request body"
  }
}

Where it's required

An Idempotency-Key header is required on these POST endpoints.

• POST /events
• POST /registration