Error Codes

Error Response Format

All tools return structured errors with AI-actionable recovery suggestions:

{
  "status": "error",
  "error": {
    "error_code": "MISSING_PREREQUISITE",
    "message": "review_trip must be called before confirm_trip",
    "ai_suggestion": "Call review_trip first to generate a trip summary",
    "do_not_retry": false
  }
}

Error Code Reference

Code	When	AI Recovery
NO_SESSION	No session_id or session not found	Call verify_member first
SESSION_EXPIRED	Session TTL (1h) exceeded	Call verify_member again
VERIFICATION_FAILED	Member not found or mismatch	Re-confirm Medicaid ID, name, DOB
INVALID_ADDRESS	Address cannot be resolved	Ask for more specific address
ADDRESS_AMBIGUOUS	Multiple addresses matched	Present candidates, ask to choose
INVALID_DATE	Date/time cannot be parsed	Ask for date in standard format
MISSING_PREREQUISITE	Tool called out of sequence	Call the required tool first
INELIGIBLE	Member not eligible for service	Inform member, check benefits
TRIP_LIMIT_EXCEEDED	All allowed trips used	Inform member of limit
BOOKING_WINDOW	Date outside booking window	Choose date within allowed range
DRAFT_NOT_FOUND	No active booking draft	Call verify_member to create draft
TRIP_ALREADY_EXISTS	Trip already booked at this time	Ask for different date/time
INVALID_SCHEDULE	Appointment time invalid or past	Confirm date/time with member
TRIP_NOT_FOUND	Trip not found (cancelled/completed)	Call get_active_trips to check
INTENT_REQUIRED	Member already has a contact record on file (email or phone) that would be silently displaced. Returned by update_member_email / update_member_phone when an intent arg is missing AND the new value does not exact-match any existing row.	Ask the member how to proceed and re-call with intent=replace, intent=add_secondary, intent=add_as_primary, or intent=correct_typo. See INTENT primitive for the full contract.
INVALID_TREATMENT_TYPE	Caller-supplied treatment_type could not be resolved against the org’s per-LOB catalogue. Returned by set_booking_details when the input matches 2+ candidates (ambiguous) or matches none. The error envelope carries did_you_mean (top-3 alphabetical, ambiguous case) or available (top-10 alphabetical, no-match case).	If did_you_mean is provided, ask the member which to use. Otherwise pick from available and re-call with the chosen value. On cache miss (empty available + an underlying error), call verify_member again to refresh the reference-data cache.
INTERNAL_ERROR	Internal service error	Retry or escalate

Sequence Gates

Each tool enforces a sequence gate via domain.ValidateSequenceGate():

Tool	Requires
set_booking_details	Session exists, draft exists
assign_driver	service_type set
review_trip	All 6 required fields: pickup_address, dropoff_address, appointment_time, trip_type, transport_mode (or service_type/service_type_id), treatment_type (or treatment_type_id) (+ return_type for roundtrip)
confirm_trip	draft.LastStep == "review" + EnrollmentID for MR

Invalid sequence calls return a MISSING_PREREQUISITE error with ai_suggestion for recovery.

Error Classification

The ClassifyError function maps internal errors to the appropriate error code:

• Domain validation errors map to specific codes (INVALID_ADDRESS, INVALID_DATE, etc.)
• Session/draft not found errors map to NO_SESSION / DRAFT_NOT_FOUND
• Downstream service errors map to INTERNAL_ERROR
• All errors include an ai_suggestion field to help agents recover automatically