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	`changes` that aren’t `APPLIED`	The call ran, but nothing was saved	See Changes and choices
4	`screeningAlerts` (prescriptions and orders)	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
`OperationError`	The call failed. Its `type` says how.	See below

An OperationError has these fields:

Field	Description
`type`	`UNAUTHORIZED`: the token can’t do this, such as a machine token trying to sign. `UPSTREAM_SERVICE`: a Photon service failed.
`code`	The specific failure, such as `PRESCRIPTION_SIGNING_UNAUTHORIZED`
`message`	A description to log
`requiredPermission`	The permission the token is missing, when Photon knows it. `UNAUTHORIZED` only.
`service`	The service that failed. `UPSTREAM_SERVICE` only.
`retryable`	Whether retrying can help. Always `false` for `UNAUTHORIZED`.

... on OperationError { type code message requiredPermission retryable }

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

3. Changes that weren’t applied

Each change in changes has a status:

APPLIED: saved. Nothing to do, unless it’s ADVISORY.
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. On an OperationError, retry only when retryable is true.
Resolve the changes that aren’t APPLIED and resend.
Show ADVISORY changes and screening alerts to the person responsible.

Network

GraphQL

MCP

Webhooks

1. Top-level errors

2. Result types

3. Changes that weren’t applied

Checklist

​1. Top-level errors

​2. Result types

​3. Changes that weren’t applied

​Checklist

1. Top-level errors

2. Result types

3. Changes that weren’t applied

Checklist