Errors

The Partner API returns errors from two layers, and they have different response shapes. Telling
them apart is the first step in debugging any failure.

Gateway errors

Our API gateway rejects some requests before they reach the application. These return a bare
message object:

{ "message": "Forbidden" }

The second message is misleading — it is the gateway's generic response for an unmatched route and
has nothing to do with your credentials. If you see it, compare your URL against
Environments & Base URLs.

Application errors

Everything else returns the PartnerApiError envelope:

{
  "error": {
    "type": "BadRequestException",
    "message": {
      "message": [
        "lastName should not be empty",
        "dateOfBirth must be a valid ISO 8601 date string"
      ],
      "error": "Bad Request",
      "statusCode": 400
    },
    "statusCode": 400,
    "timestamp": "2026-07-29T16:56:56.150Z",
    "details": []
  },
  "path": "/v2/clinicians/:clinicianId/clients"
}

Because error.message is either an object or a string, extract it defensively:

function describe(err) {
  const m = err?.error?.message
  if (typeof m === 'string') return m
  if (Array.isArray(m?.message)) return m.message.join('; ')
  return `HTTP ${err?.error?.statusCode ?? 'unknown'}`
}

Status codes

404 is the one to plan for

Every path parameter is checked for ownership: the organization, clinic, clinician, client, session,
progress note, summary, or assessment score you name must belong to your partner organization. If it
does not, you get 404.

A resource that does not exist and a resource that belongs to another partner return the identical
404. That is deliberate — the API never confirms whether an ID exists in someone else's data — so you
cannot tell the two apart, and should not try.

In practice a 404 on a well-formed request almost always means one of:

• You are using a sandbox ID against production, or vice versa
• You stored an ID from a different partner environment
• You constructed a UUID rather than using one Blueprint returned

Progress notes are the one application-level 403 left. Once a note is finalized it is locked, and
these return 403 with the message Progress note is locked:

• PATCH /progress-notes/{progressNoteId}
• POST /progress-notes/{progressNoteId}/magic-edit
• POST /progress-notes/{progressNoteId}/regenerate

Listen for the progress_note_finalized webhook to know when a note has crossed that line. See
Webhook Events Reference.

Clinical artifacts that are not ready yet

Transcripts, summaries, progress notes, and MDM elements are generated asynchronously. Requesting
one before it exists is a normal condition, not an error, and there are two distinct signals:

Still generating. GET /sessions/{sessionId}/progress-note returns 200 with
isLoading: true and an empty or partial note array. Poll, or better, wait for the
progress_note_generated webhook.

Never generated. For GET /sessions/{sessionId}/transcript and
GET /sessions/{sessionId}/mdm, a missing artifact currently returns HTTP 200 with a body
describing the error rather than a 404. Do not rely on the status code for these two endpoints —
check whether the expected fields (transcriptItems, problemsAddressed) are present:

const res = await fetch(transcriptUrl, { headers })
const body = await res.json()
if (!body.transcriptItems) {
  // not available yet — retry later or wait for `transcript_ready`
}

This is a known defect and will change to a 404. Write your check against the response body, not
the status code, so a future fix does not break you.

The reliable pattern for all four artifacts is to wait for the corresponding webhook and fetch the
URL it gives you. See Listening to Webhooks.

Retries

The API does not support idempotency keys, so retries are not automatically safe. See
Pagination & Limits for what is and is not safe to retry.

Recommended handling: