Errors
How the Awell Orchestration API signals success and failure through the code and success envelope, plus GraphQL errors.
The Orchestration API reports outcomes through a code and success envelope on every response
payload, and through standard GraphQL errors for request-level failures. Check both.
Start here: a failed request usually still returns HTTP 200. Being GraphQL, this API reports
problems in the response body, not in the status code — an invalid field name and a record that
does not exist both come back 200 OK. Code that branches on the HTTP status alone will treat those
as successes.
The response envelope
Every operation returns a payload that includes two fields:
| Field | Type | Description |
|---|---|---|
success | Boolean! | Whether the operation succeeded. |
code | String! | A status code describing the outcome. |
success is the field to branch on. It is on every payload object, and for a mutation it is the
only reliable way to know whether the write happened. code accompanies it as a string describing
the outcome; Awell does not publish an enumerated list of its values, so treat it as something to
log and read when diagnosing rather than something to switch on in code.
GraphQL errors
For request-level failures such as malformed queries, authentication failures, or server errors,
the response includes a top-level errors array, as defined by the
GraphQL specification. A response can contain both data and
errors.
{
"data": null,
"errors": [
{
"message": "...",
"path": ["patient"]
}
]
}Awell does not publish a set of machine-readable codes on these errors, so match on the shape of the
response and the message, not on a code that may not be there.
What the HTTP status does tell you
| Status | What it means |
|---|---|
200 | The request reached the API and was executed. It may still have failed — read errors and success. |
4xx | Uncommon here, and usually your network or connection rather than your query. GraphQL reports query problems inside a 200. |
5xx | An error inside Awell. Retry, and contact support if it persists. |
5xx is the only status worth an automatic retry. Retrying a 200 that contained an error just
repeats the same failure.