Idempotency

Network issues happen — if a request to a write endpoint times out, you can't always tell whether it actually went through. Send an Idempotency-Key header on any POST or PATCH request and it's safe to retry.

How it works

Use any unique string you like — a UUID is the usual choice.
The first request with a given key is processed normally, and its response is cached against that key.
A retried request with the same key and the same body gets back the exact same response — no matter how many times you retry.
A retried request with the same key but a different body is rejected with a 409 — reusing a key for a genuinely different request is a bug on the caller’s side, not something RideLoop will silently paper over.
Keys are retained for 24 hours, then pruned — reuse a key from longer ago and it’s treated as new.
Endpoints that don’t change anything (every plain GET) don’t use idempotency keys at all.

Example

const idempotencyKey = crypto.randomUUID()

async function createBooking() {
  const response = await fetch('https://your-rideloop-domain/api/v1/bookings', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer rlk_...',
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({
      categoryId: '…',
      size: 'M',
      startDate: '2026-08-01',
      endDate: '2026-08-03',
      guestName: 'Jane Doe',
      guestEmail: 'jane@example.com',
    }),
  })
  return response.json()
}

// Safe to call again on a timeout/network error — the same idempotencyKey
// and body always replay the same { reference: "RB-2026-000124", ... } response.
const booking = await createBooking()