Skip to navigation

Retries and idempotency

View as Markdown

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:

  1. Do not create a new key.
  2. Retry the same method, path, body, selected organization, and Trutee-Version with the same key.
  3. A recovered response includes Idempotency-Replayed: true. Its resource representation is the original result; Request-Id and meta.request_id identify the current HTTP attempt.
  4. 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.
Complete recovered HTTP response
{
"status": 201,
"headers": {
"Trutee-Version": "2026-07-29",
"Request-Id": "req_retry_attempt",
"Idempotency-Replayed": "true",
"RateLimit-Limit": "60",
"RateLimit-Remaining": "58",
"RateLimit-Reset": "1785333660"
},
"body": {
"data": {
"id": "res_example_encrypted",
"status": "confirmed",
"course_id": "crs_example_encrypted",
"external_reference_id": "external-order-1042",
"guest": {
"first_name": "Avery",
"last_name": "Jordan",
"email": "avery@example.com",
"phone": "+13035550142"
},
"allocations": [
{
"tee_time_id": "ttm_example_encrypted",
"quantity": 2,
"time": {
"starts_at": "2026-08-15T14:10:00.000Z",
"local_date": "2026-08-15",
"local_time": "08:10",
"timezone": "America/Denver"
},
"selections": { "holes": 18, "cart": "riding" },
"pricing": {
"green_fee": { "amount_minor": 8500, "currency": "USD" },
"cart_fee": { "amount_minor": 1800, "currency": "USD" },
"total_per_golfer": { "amount_minor": 10300, "currency": "USD" }
},
"known_companions": [{ "first_name": "Morgan", "last_name": "Lee" }]
}
],
"golfer_count": 2,
"payment": {
"method": "pay_at_course",
"amount_due_now_minor": 0,
"currency": "USD"
},
"cancellation_policy": {
"window_hours": 24,
"fee": { "amount_minor": 2500, "currency": "USD" },
"policy_fingerprint": "policy_2026_07"
},
"cancellation_eligibility": {
"allowed": true,
"code": "allowed",
"message": "This Reservation may be cancelled through the API.",
"contact_course": false
},
"integration_attribution": {
"organization_name": "Example Travel",
"source": "public_api"
},
"created_at": "2026-07-29T14:01:00.000Z",
"updated_at": "2026-07-29T14:01:00.000Z",
"cancelled_at": null,
"messaging": {
"owner": "integration",
"trutee_confirmation_suppressed": true,
"trutee_cancellation_suppressed": true,
"course_name": "Pine Ridge Golf Club",
"guest_name": "Avery Jordan",
"allocations": [
{
"time": {
"starts_at": "2026-08-15T14:10:00.000Z",
"local_date": "2026-08-15",
"local_time": "08:10",
"timezone": "America/Denver"
},
"quantity": 2,
"selections": { "holes": 18, "cart": "riding" }
}
]
}
},
"meta": {
"request_id": "req_retry_attempt"
}
}
}

Retry policy

  • Retry 429 after the whole seconds in Retry-After.
  • Treat 429, 502, 503, and 504 as retryable with exponential backoff, jitter, and a bounded attempt/time budget. Honor Retry-After on 429. The dated application contract currently emits 503 inventory_read_limit_exceeded; gateways may produce 502 or 504.
  • Do not automatically retry 500 internal_error; email support@trutee.app with the Request-Id when the failure persists.
  • Do not automatically retry other 4xx responses. 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.