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

# Errors

> Stable structured errors, status semantics, and recovery.

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.

| Status | Codes                                                                                                                                                                                                                                                                                                                                                                                                                                         | Recovery                                                  |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| 400    | `allocations_must_share_course`, `allocations_must_share_date`, `cursor_scope_mismatch`, `duplicate_allocation`, `idempotency_key_required`, `invalid_course_id`, `invalid_cursor`, `invalid_idempotency_key`, `invalid_json`, `invalid_limit`, `invalid_play_date`, `invalid_play_date_range`, `invalid_reason`, `invalid_request`, `invalid_status`, `invalid_updated_after`, `search_too_broad`, `unsupported_version`, `version_required` | Correct the request; do not blindly retry                 |
| 401    | `invalid_oauth_client`, `unauthorized`                                                                                                                                                                                                                                                                                                                                                                                                        | Obtain a valid OAuth access token                         |
| 403    | `forbidden`, `organization_required`, `unsupported_organization_role`                                                                                                                                                                                                                                                                                                                                                                         | Reauthorize with the intended organization and role       |
| 404    | `endpoint_not_available`, `not_found`, `reservation_not_found`                                                                                                                                                                                                                                                                                                                                                                                | Use a documented route, rediscover IDs, or stop           |
| 409    | `availability_conflict`, `cancellation_fee_required`, `customer_blocked`, `customer_inactive`, `customer_overlap`, `guest_identity_conflict`, `idempotency_key_reuse`, `invalid_offer`, `offer_changed`, `offer_expired`, `offer_unavailable`, `play_started`, `reservation_not_cancellable`, `reservation_state_invalid`, `integration_unavailable`                                                                                          | Follow the code-specific recovery below                   |
| 413    | `request_too_large`                                                                                                                                                                                                                                                                                                                                                                                                                           | Reduce the request body                                   |
| 429    | `rate_limit_exceeded`                                                                                                                                                                                                                                                                                                                                                                                                                         | Wait for `Retry-After`                                    |
| 500    | `internal_error`                                                                                                                                                                                                                                                                                                                                                                                                                              | Do not automatically retry; email support with Request ID |
| 503    | `inventory_read_limit_exceeded`                                                                                                                                                                                                                                                                                                                                                                                                               | Narrow the search or retry with bounded backoff           |

```json title={"Structured error"}
{
  "error": {
    "type": "conflict_error",
    "code": "cancellation_fee_required",
    "message": "The course cancellation policy requires a fee that cannot be collected through this API. Contact the course.",
    "doc_url": "https://docs.trutee.app/home/operate/errors#cancellation_fee_required",
    "request_id": "req_cancellation_denied"
  }
}

```

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](mailto: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.