Idempotency

POST requests that create or mutate resources can have side effects (for example, creating a task, charging a fee). If a request fails mid-flight — network timeout, server error — it is not safe to retry blindly without risking duplicate execution.

The Idempotency-Key header solves this: send the same key on a retry and the API returns the original response without re-executing the operation.

How to Use It

Include Idempotency-Key on every POST request. The value must be a unique string you generate (a UUID v4 is a good choice):

curl -X POST https://api-us.suiteop.com/api/v1/tasks \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"title": "Clean Unit 12B", "propertyId": "prop_01j..."}'

On a retry, send the exact same Idempotency-Key:

curl -X POST https://api-us.suiteop.com/api/v1/tasks \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"title": "Clean Unit 12B", "propertyId": "prop_01j..."}'

The response is identical to the original, with one additional header:

Idempotency-Replayed: true

Replay Window

Idempotency keys are stored for 24 hours from the original request. After that window, the same key is treated as a fresh request.

Error Cases

Scenario	Status	Error type
Same key, different request body	`422`	`business_rule_error`
Two concurrent in-flight requests with the same key	`409`	`conflict_error`
`Idempotency-Key` header present but blank (`""`)	`400`	`validation_error`

When to Use It

Use Idempotency-Key on all POST requests, especially:

Creating resources (tasks, reservations, charges) — avoid creating duplicates on network retries.
Sending messages or triggering automations — these have external side effects that cannot be undone.

GET, PATCH, PUT, and DELETE requests are naturally idempotent and do not require the header.