Skip to navigation

Errors

View as Markdown

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.

StatusCodesRecovery
400allocations_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_requiredCorrect the request; do not blindly retry
401invalid_oauth_client, unauthorizedObtain a valid OAuth access token
403forbidden, organization_required, unsupported_organization_roleReauthorize with the intended organization and role
404endpoint_not_available, not_found, reservation_not_foundUse a documented route, rediscover IDs, or stop
409availability_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_unavailableFollow the code-specific recovery below
413request_too_largeReduce the request body
429rate_limit_exceededWait for Retry-After
500internal_errorDo not automatically retry; email support with Request ID
503inventory_read_limit_exceededNarrow the search or retry with bounded backoff
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 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.