API Endpoints and Errors

Error handling and optional features for scheduling appointments at Patient Service Centers (PSCs).

API Endpoints

All endpoints require authentication and are prefixed with /v3/order:

• POST /v3/order/psc/appointment/availability - Get available time slots
• POST /v3/order/{order_id}/psc/appointment/book - Book an appointment
• PATCH /v3/order/{order_id}/psc/appointment/reschedule - Reschedule an appointment
• PATCH /v3/order/{order_id}/psc/appointment/cancel - Cancel an appointment
• GET /v3/order/{order_id}/psc/appointment - Get appointment details
• GET /v3/order/psc/appointment/cancellation-reasons - Get cancellation reasons

---

Error Handling

Environment Differences

⚠️ Important: Currently, error behavior differs between sandbox and production environments:

Environment	Quest Integration	Slot Conflict Behavior
Sandbox	Mock client	Returns 400 (mock doesn’t simulate conflicts)
Production	Real Quest API	Returns 404 (actual Quest response)

Recommendation: For now, handle both 400 and 404 responses as potential slot-unavailability scenarios.

Frequently Asked Questions

Q: Do I need to parse error messages to distinguish between different 400 errors?

Yes. Since multiple error types return 400 status codes, you must examine the error message content to determine the appropriate handling:

• Time in the past: "This appointment slot is no longer available. Please select a new time." → Select new slot
• Invalid booking key: "Invalid booking key format" → Fix request
• Missing parameters: "radius must be provided when using zip_code" → Fix request
• Order state issues: "Order is not in a state that allows booking..." → Contact support

HTTP status codes alone are insufficient because our API uses 400 for multiple distinct error categories that require different user experiences.

Error Categories

Slot Unavailability Errors

The user should select a different time slot

Status	Error Message	When It Occurs	User Action
400	"This appointment slot is no longer available. Please select a new time."	Requested time is in the past	Select a future time slot
400 or 404	Quest-specific error messages	Slot already taken or no longer exists	Select a different time slot
404	"No slots found for zip code"	No locations/slots in the area	Try a different location or date range
404	"No slots found. Not all PSCs support scheduling..."	All locations lack scheduling capability	Use different locations

Input Validation Errors

Fix the request parameters

Status	Error Message	When It Occurs	User Action
400	"Invalid booking key format"	Malformed or corrupted booking key	Refresh availability and get a new booking key
400	"Location with site code {code} not found"	Invalid PSC location code	Use a valid site code from the availability API
400	"Location with site code {code} is no longer active"	PSC location disabled	Select a different location
400	"start_date must be greater or equal than the current date"	Past date in the availability request	Use current or future date
400	"site_codes or zip_code must be provided"	Missing search parameters	Provide either site codes or zip code
400	"radius must be provided when using zip_code"	Missing radius with zip code search	Include radius parameter
400	"site_codes must be less than or equal to 3"	Too many site codes	Limit to 3 site codes maximum
404	"This order doesn't exist."	Invalid order ID	Verify order ID is correct
404	"This order is not a walk-in phlebotomy order."	Wrong order type	Use the correct order type

Order State Errors

Order workflow or business logic issues

Status	Error Message	When It Occurs	User Action
400	"Order is not a walkin phlebotomy order"	Wrong order type for PSC booking	Contact support
400	"Order does not have a sample ID..."	Order missing requisition	Wait for requisition or contact support
400	"Order is not in a state that allows booking..."	Order workflow prevents booking	Contact support
400	"Order is not in a state that allows cancelling..."	Order workflow prevents cancellation	Contact support
400	"Order is not in a state that allows rescheduling..."	Order workflow prevents rescheduling	Contact support
400	"This order does not have a requisition..."	Missing requisition for appointment	Wait or contact support
400	"This lab is not supported."	Order not for Quest lab	Use a supported lab

Appointment Management Errors

Appointment-specific business rules

Status	Error Message	When It Occurs	User Action
400	"This order doesn't have an appointment yet."	Trying to modify a non-existent appointment	Book an appointment first
400	"This appointment cannot be rescheduled."	Appointment marked non-reschedulable	Cancel and book a new appointment
400	"This appointment has been cancelled or completed."	Operating on finalized appointment	No further action is possible
400	"This appointment has already been cancelled."	Cancelling already cancelled appointment	No action needed
404	"Appointment not found."	Appointment doesn’t exist	Verify appointment exists

Authorization Errors

Access control issues

Status	Error Message	When It Occurs	User Action
401	Authentication error	Invalid or expired token	Re-authenticate
403	"Action forbidden"	User lacks permission for the order	Contact support

Service Availability Errors

System configuration or availability

Status	Error Message	When It Occurs	User Action
503	"Feature not enabled"	PSC scheduling disabled	Contact support or try later

Testing Error Scenarios

Sandbox Testing

• Most validation errors can be tested in sandbox
• Slot conflicts cannot be reliably tested (mock client always succeeds)
• Use invalid parameters to test input validation

Production Testing

• Test with caution using real appointments
• Slot conflicts will return actual 404 errors from Quest
• Time-based errors can be tested with past dates

Quest API Limitations

• Timeout: 15 seconds read timeout, 5 seconds connection timeout
• Slot availability: Real-time, can change between availability check and booking
• Mock client: Doesn’t simulate all real-world scenarios
• Rate limiting: Standard Quest API rate limits apply