Idempotency

Retry safely. Use Idempotency-Key on every write that could fail mid-flight.

The contract

POST / PATCH requests accept an optional Idempotency-Key header. Any string ≤ 255 chars; a UUID is the conventional choice. The first request processes normally; subsequent requests with the same key replay the stored response.

POST https://api.prearrive.com/v1/reservations
Authorization: Bearer prearrive_live_sk_…
Idempotency-Key: 8c5a1f0d-b822-4644-c1da-9f476e350bd2
Content-Type: application/json

{ "property_id": "prop_…", "guest_name": "Avery", "guest_email": "avery@example.com",
  "checkin_date": "2026-06-12", "checkout_date": "2026-06-15", "source": "airbnb" }

What happens behind the scenes

1. We hash your request body with SHA-256.
2. We store the tuple (team_id, idempotency_key, body_hash, status, response_body, response_headers) in KV with a 24-hour TTL.
3. The next request with the same key + same body returns the stored response byte-for-byte. The response carries Idempotent-Replay: true.
4. The next request with the same key + a different body returns 422 idempotency_key_mismatch.
5. After 24h the key is forgotten and the next request processes normally.

When to use it

• Always on POST when you're creating a resource that costs the team something (a reservation, a property pack, anything that triggers a metered API event).
• Always on POST /reservations/{id}/send — even though /send itself is idempotent server-side (already-sent returns the current row), an Idempotency-Key protects against the case where the request body schema changes between retries.
• Optional but recommended on PATCH when you have automation that retries on a flaky network.

Generating keys

Mint a fresh key per logical write. Don't reuse across different actions, even if the body is identical — that defeats the body-hash check.

# Node
const k = crypto.randomUUID();

# Python
import uuid; k = str(uuid.uuid4())

# Bash
k=$(uuidgen)

Error responses

Status	Code	When
400	idempotency_key_too_long	Key > 255 chars.
422	idempotency_key_mismatch	Key reused with a different request body.

What's NOT replayed

• GET requests — they're naturally idempotent.
• DELETE — naturally idempotent.
• Responses with status ≥ 400 — we don't cache failures (so you can retry around a transient error and actually re-attempt the write).

Related: Test mode · Versioning · Full API reference