Errors
Errors use a stable envelope with type, code, human-readable message, optional param, doc_url, and request_id. Branch on status and code, not message text. Save the matching Request-Id header.
New error codes and enum values may be added compatibly. Treat unknown values conservatively and surface them for operator review.
Code-specific recovery
Every emitted doc_url targets one of these stable fragments.
Request and version errors
allocations_must_share_course — Put allocations for different Inventory
Courses in separate Reservations.
allocations_must_share_date — Put allocations for different course-local dates
in separate Reservations.
cursor_scope_mismatch — Restart pagination and keep every filter and the page
size unchanged.
duplicate_allocation — Include a Tee Time only once in a Reservation request.
idempotency_key_required — Supply an Idempotency-Key on every state-changing
request.
invalid_course_id — Rediscover the course and use the dated API’s opaque ID
unchanged.
invalid_cursor — Discard the cursor and restart the traversal.
invalid_idempotency_key — Use a key containing 8–255 characters.
invalid_json — Send a valid JSON body.
invalid_limit — Use the endpoint’s documented integer page-size range.
invalid_play_date — Use a real calendar date in YYYY-MM-DD form.
invalid_play_date_range — Order the inclusive range and keep it within 366
days.
invalid_reason — Omit the cancellation reason or send a non-empty value of at
most 500 characters.
invalid_request — Correct the field identified by param and remove
unsupported fields.
invalid_status — Use a documented Reservation status.
invalid_updated_after — Send a valid RFC 3339 timestamp with an explicit UTC
offset.
search_too_broad — Add course IDs or bounded geo filters so at most 10
accessible courses resolve.
unsupported_version — Send a currently supported dated Trutee-Version.
version_required — Add the required Trutee-Version header.
request_too_large — Keep Reservation creation at or below 64 KiB (65,536
bytes) and cancellation at or below 8 KiB (8,192 bytes), measured on the encoded
JSON body.
Authentication and authorization errors
invalid_oauth_client — Obtain a token issued to a valid OAuth client.
unauthorized — Obtain a valid, unexpired OAuth access token.
forbidden — Verify current membership and the exact role required by the
operation.
organization_required — Reauthorize and select the intended organization
organization.
unsupported_organization_role — Use a supported exact organization role;
unknown roles fail closed.
reservation_not_found — Rediscover the Reservation in the selected
organization; unknown and cross-organization IDs are indistinguishable.
not_found — Correct the public route.
endpoint_not_available — The method is not available on that public route; use
the generated reference.
Conflict and policy errors
availability_conflict — Search again; capacity or overlap state changed before
the atomic write.
integration_unavailable — Reauthorize the intended organization and retry only
after its access is restored.
cancellation_fee_required — The API cannot collect the fee; contact the
Inventory Course.
customer_blocked — Do not retry automatically; contact the Inventory Course.
customer_inactive — Do not retry automatically; contact the Inventory Course.
customer_overlap — Resolve the Guest Golfer’s overlapping booking before
retrying.
guest_identity_conflict — Correct the Guest Golfer identifiers or contact the
Inventory Course.
idempotency_key_reuse — Treat this as a caller bug: within the same principal,
operation, and path, the key was reused with a different canonical body.
Different principals, operations, or paths are independent scopes, though
globally unique keys remain safest.
invalid_offer — Discard the offer, search availability again, and use a new
booking idempotency key.
offer_changed — Search again and review the changed quantity, policy,
selection, or price.
offer_expired — Search again; offers expire after five minutes and are not
Holds.
offer_unavailable — Search again or choose another Inventory Course or Tee
Time.
play_started — The API cannot cancel after play begins; contact the Inventory
Course.
reservation_not_cancellable — Keep the Reservation active and contact the
Inventory Course.
reservation_state_invalid — The API could not safely release the whole group;
contact the Inventory Course.
Capacity and service errors
rate_limit_exceeded — Wait for Retry-After, then retry within a bounded
budget.
internal_error — Do not automatically retry; give support the Request-Id if
the failure persists.
Email support@trutee.app with the endpoint, UTC timestamp, HTTP status, error code, and Request-Id. Do not send bearer tokens or guest PII.
inventory_read_limit_exceeded — Retry a transient failure with bounded
backoff. For POST /reservations, preserve the same body and idempotency key
when retrying that logical request. Narrowing allocations or course-days changes
the body, so submit it as a new logical request with a new key. For
availability, narrow the search.

