PSC Scheduling API: Errors and Features

​

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

​

Input Validation Errors

Fix the request parameters

​

Order State Errors

Order workflow or business logic issues

​

Appointment Management Errors

Appointment-specific business rules

​

Authorization Errors

Access control issues

​

Service Availability Errors

System configuration or availability

​

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

---

​

Beta Features

​

Availability Cache

Junction maintains a fast Availability Cache containing the next 21 days of availability for all locations. Each location is refreshed every 5 minutes on average. When you set the allow_stale parameter on the PSC Appointment Availability endpoint, your request is fulfilled directly from the Availability Cache, provided that:

1. All requested locations have a cache hit; and
2. The cached information is reasonably fresh (less than 15 minutes old).

When a request cannot be fulfilled by the Availability Cache, it is routed directly to the PSC Appointment Provider.

​

When to use

Use allow_stale when you need fast response times and can tolerate slightly stale availability data—for example, when displaying initial availability options to a user before they select a specific slot.

​

Idempotency Key

Consider specifying an Idempotency Key (X-Idempotency-Key header) when submitting a booking request to the Book PSC Appointment endpoint. Requests with the same idempotency key within a 14-day retention window will return the original request’s response. Note that the response is frozen at the time it is first emitted. For example, if a pending appointment later transitions to confirmed via Async Confirmation, requests with that idempotency key will still return the appointment in its original pending status.

​

When to use

When a booking request fails on your side (API consumer side), it could be a transient connection issue or a Junction request queueing issue. Your request might have still reached the Junction API server and might have been processed. Using an Idempotency Key allows your system to safely retry booking requests, without the risk of double booking appointments.

​

Async Confirmation

When calling the Book PSC Appointment endpoint, Junction by default returns a 500 Internal Server Error if the PSC Appointment Provider fails to acknowledge the booking request. With Async Confirmation enabled, Junction waits synchronously for the provider to acknowledge the booking request, up to sync_confirmation_timeout_millisecond (default: 2.5s, range: 1–10s).

• If an acknowledgement is received before the timeout, Junction creates a reserved or confirmed appointment immediately and returns it in the response.
• If no acknowledgement is received before the timeout, Junction creates a placeholder pending appointment and returns it in the response.

​

Background retries

If a pending appointment is created, Junction continues to retry the booking request with the PSC Appointment Provider in the background, up to async_confirmation_timeout_millisecond (default: 15min, range: 1min–48hr).

• If an acknowledgement is received before the timeout, the appointment transitions to reserved or confirmed status.
• If the provider still fails to acknowledge after the timeout, the pending appointment transitions to cancelled status.

​

Webhooks

You will receive the labtest.appointment.updated event for the initial appointment creation, as well as for all state transitions described above.

​

When to use

Use Async Confirmation when you want to provide a consistently responsive booking experience. When the PSC Appointment Provider is under stress, Async Confirmation allows you to show a pending appointment to the end patient, and manages all the logistics to retrying the booking requests with the provider.