Retries and idempotency
All state-changing requests require an Idempotency-Key of 8–255 characters. Generate a unique key per logical operation and retain it with the exact path and canonical request body for at least 24 hours.
Ambiguous write recovery
If POST /reservations or a cancellation times out after transmission:
- Do not create a new key.
- Retry the same method, path, body, selected organization, and
Trutee-Versionwith the same key. - A recovered response includes
Idempotency-Replayed: true. Its resource representation is the original result;Request-Idandmeta.request_ididentify the current HTTP attempt. - Within the same principal, operation, and path, reusing the key with a different canonical body returns
409 idempotency_key_reuse; treat it as a caller bug. A different principal, operation, or path is an independent idempotency scope, but globally unique keys remain the safest client practice.
Retry policy
- Retry
429after the whole seconds inRetry-After. - Treat
429,502,503, and504as retryable with exponential backoff, jitter, and a bounded attempt/time budget. HonorRetry-Afteron429. The dated application contract currently emits503 inventory_read_limit_exceeded; gateways may produce502or504. - Do not automatically retry
500 internal_error; email support@trutee.app with theRequest-Idwhen the failure persists. - Do not automatically retry other
4xxresponses. Refresh an expired offer with/availability; resolve a cancellation denial or blocked guest explicitly. - Reads are safe to retry. Preserve all filters and cursor while traversing a page set.
Rate-limit headers use fixed one-minute buckets. Reads allow 300/minute and writes allow 60/minute per user, bearer credential, and resolved organization principal. Availability fanout allows 30/minute shared by the bearer credential and resolved organization. RateLimit-Reset is a Unix timestamp in seconds.
Log status, error code, Request-Id, idempotency key, and External Reference ID (external_reference_id) without logging bearer tokens, guest PII, or opaque offer contents.

