Errors

Check each response in this order:

	Where	Means	Do
1	Top-level `errors`	The call didn’t run: a bad token or an invalid query	Fix the token or query. Retrying unchanged fails again.
2	The result’s `__typename`	The call failed, or needs you to pick a record	See below
3	`unappliedChanges`	The call ran, but some inputs weren’t saved	See Changes and choices
4	`screeningAlerts` (prescriptions)	Clinical conflicts	Show them to the prescriber. See Screening.

1. Top-level errors

No mutation ran, and data is empty:

{ "errors": [{ "message": "An authentication token is not present", "extensions": { "code": "EMPTY_AUTHORIZATION_HEADER" } }] }

The same happens with an expired token, an unknown field or a wrong argument type.

2. Result types

`__typename`	Means	Do
`…Payload`	The call ran	Go to step 3
`AmbiguousPatientMatch`	Several patients could match, and nothing was saved	Resend with one of the `candidates`’ `id`, or with more details
`AmbiguousPrescriptionMatch`	The patient has several drafts in progress, and you didn’t send an `id`	Resend with the `id` of the draft you mean
`AmbiguousOrderMatch`	The patient has several draft orders, and you didn’t send an `id`	Resend with the `id` of the order you mean
`UnauthorizedError`	The token can’t do this, such as a machine token trying to sign	Use the right token. Don’t retry.
`UpstreamServiceError`	A Photon service failed	Retry with backoff if `retryable` is true

PatientPayload.patient and Order.patient can also be an UpstreamServiceError. That means the call was processed, but the patient couldn’t be read back.

3. Unapplied changes

Each entry has a status:

REJECTED: fix the input that reason describes. Skip entries that were rejected only because another input failed.
AMBIGUOUS: choose one of the options and resend.

Then resend the whole call.

Checklist

If errors is present, stop and fix the token or query.
Branch on __typename. Resend ambiguous matches with an id. Retry UpstreamServiceError only when retryable is true.
Resolve unappliedChanges and resend.
Show ADVISORY changes and screening alerts to the person responsible.

Network

GraphQL

MCP

Webhooks

1. Top-level errors

2. Result types

3. Unapplied changes

Checklist

​1. Top-level errors

​2. Result types

​3. Unapplied changes

​Checklist

1. Top-level errors

2. Result types

3. Unapplied changes

Checklist