> 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.

# Troubleshooting and gotchas

> Common integration mistakes and the safest correction.

**`organization_required`** — The user did not select an organization during OAuth consent. Reauthorize and select the approved organization.

**`forbidden` on Reservation operations** — The selected organization or user was not provisioned with Reservation capabilities. Ordinary administrator access does not automatically grant Public API booking access.

**Availability returns only public inventory** — Verify the selected organization and role. Effective access is returned on courses and offers.

**An offer expired or changed** — Offers live for five minutes and are not holds. Search again, build a new request, and use a new idempotency key.

**`cursor_scope_mismatch`** — Reuse the same filters and limit for every page. Start a new traversal when filters change.

**A write timed out** — Retry the identical method, path, body, version, principal, and idempotency key. Do not send guest messaging until recovery succeeds.

**Cancellation was denied** — The Reservation remains active. Contact the course when a fee, started play, or unsafe state requires it.

**Need to change a Tee Time or party** — Retrieve, search replacement availability, then cancel and rebook. Do not mutate in place.

**Times look shifted** — Display `local_date` and `local_time` in `timezone`; use `starts_at` for UTC ordering. Do not apply a fixed offset.

**Money looks 100× too large** — Amounts are integer minor units. `8500 USD` is `$85.00`.

**Duplicate confirmation** — Key messaging delivery by Reservation ID and event. An idempotent replay returns the same resource with a new request ID.

For support, email [support@trutee.app](mailto:support@trutee.app) with the endpoint, UTC timestamp, status, error code, `Request-Id`, External Reference ID (`external_reference_id`), and non-sensitive idempotency key. Never send access tokens or guest PII in support logs.