> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trutee.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trutee.app/_mcp/server.

# Retries and idempotency

> Safe recovery from timeouts, rate limits, transient failures, and ambiguous writes.

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.

```json title={"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](mailto: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.