Conventions
Idempotency & retries
Which methods are safe to retry, and what isn't
Safe by HTTP method
| Method | Safe to retry? | Notes |
|---|---|---|
GET | Yes | Always idempotent. |
DELETE | Yes | Deleting an already-deleted resource returns 404, which is safe to ignore. |
PATCH | Usually | Most PATCHes set fields to absolute values, so re-applying the same payload is harmless. |
PUT | Yes | Replaces the resource — re-applying is a no-op. |
POST | No | Creation endpoints will create duplicate resources on retry. |
Idempotency-Key header
The API does not currently honour an Idempotency-Key request header. Tracked for a future
release.
Until idempotency keys ship, follow these patterns for at-most-once delivery on
POST:
- Generate the resource ID client-side where the endpoint allows it
(e.g. external reference IDs on guests/expenses) — re-posting the same ID
surfaces a
409instead of creating a duplicate. - Check before creating —
GETwith a filter, onlyPOSTif absent. Tolerates the race; pair with a unique constraint on the server. - Use the bulk endpoints where available — bulk endpoints often dedupe server-side.
Retry budget
For automated retries on 5xx and 429:
- Cap attempts at 5.
- Exponential backoff:
min(2^attempt, 60)seconds, with ±20% jitter. - Surface the failure after the budget is exhausted; do not retry forever.