Errors & pagination

The error envelope

Every non-2xx response carries a JSON body of one shape:

{
  "error": {
    "code": "has_open_thread",
    "message": "Patient already has an open async consult",
    "details": {"asyncConsultId": "aB3xK9mQpZ4r"}
  }
}
Copy

Branch on code — it is machine-readable and stable. message is for logs (wording may change without notice), and details is optional structured context: validation issues for invalid_request, a conflicting resource id for some 409s. New codes may be added within /v1; treat an unknown code by its HTTP class (4xx = your request, 5xx = ours).

Error code catalog

The HTTP status is fully determined by the code (the server derives it from the same table, ERROR_HTTP_STATUS, so the two cannot disagree). Full per-code semantics live on ErrorCode.

How to think about 409s

Every 409 (other than feature_disabled) is a state conflict: the consult moved between your last read and your write — the underlying store applies lifecycle transitions as conditional writes, so a stale operation fails loudly instead of double-applying. The recovery is always the same: re-read the resource, then retry only if the operation still makes sense. A retry that finds the work already done gets a descriptive 409 (already_closed, not_assigned, …), never a double-application.

Idempotency & retry safety

The 202 message flow

POST /v1/async-consults/{id}/messages and …/replies return 202 Accepted: the message passed validation and was enqueued into the per-patient FIFO pipeline — it had not yet been processed when the response was sent, but it will appear on the transcript in order. The 202 body reports the messageId the message will carry on the transcript and in webhooks.

To observe delivery:

• Push: the async_consult.message webhook fires when the message lands on the transcript.
• Pull: re-read GET /v1/async-consults/{id}/messages.

One asynchronous edge: if the thread closes after your 202 but before the message processes, the message cannot be routed — you receive an async_consult.message_rejected webhook naming your messageId. An accepted patient message is never silently dropped; surface the rejection in your patient UI. (The synchronous sibling — the thread was already closed at post time — is the immediate 409 message_rejected / 409 thread_not_active instead.)

Pagination

Every list endpoint uses the same cursor contract ( Page):

GET /v1/async-consults?status=active&limit=50
→ {"items": [...], "nextCursor": "eyJ..."}

GET /v1/async-consults?status=active&limit=50&cursor=eyJ...
→ {"items": [...]}            ← no nextCursor: last page
Copy

Rules:

• limit is 1–100; a server default applies when omitted.
• nextCursor present ⇒ more results; pass it back verbatim as cursor. Absent ⇒ you've reached the end. (An empty items with no nextCursor is also a valid end.)
• Cursors are opaque and endpoint-specific: don't parse them, don't store them long-term, and never reuse a cursor across endpoints or with different filter parameters.
• Sort orders are fixed per endpoint: async consults by lastActivityAt descending, telehealth consults newest first, transcripts (…/messages) oldest first, events (GET /v1/events) oldest first.