Reference

Errors

An error is a non-2xx status with a JSON body. Every response, success or error, also carries an x-request-id header; quote it when you ask Protearc about a request.

The error shape

Most errors have one field, detail, a short string:

A request the API cannot read, for example a body with a field it does not accept, is 422 and detail is a list with one entry per problem: the kind of problem (type), where it is (loc), a message (msg) and the value that was sent (input).

Write your client to branch on the status code first, then on the detail string where the table below lists one.

json Response 401

{ "detail": "invalid token" }

json Response 422, an order with a name in it

{
  "detail": [
    {
      "type": "extra_forbidden",
      "loc": ["body", "name"],
      "msg": "Extra inputs are not permitted",
      "input": "Example Person"
    }
  ]
}

curl -i http://localhost:8000/v1/members/PA-0001/reports \
  -H "Authorization: Bearer ptk_not_a_real_token"

import requests

r = requests.get(
    "http://localhost:8000/v1/members/PA-0001/reports",
    headers={"Authorization": "Bearer ptk_not_a_real_token"},
)
print(r.status_code, r.json()["detail"])  # 401 invalid token

const r = await fetch("http://localhost:8000/v1/members/PA-0001/reports", {
  headers: { Authorization: "Bearer ptk_not_a_real_token" },
});
console.log(r.status, (await r.json()).detail); // 401 invalid token

Status codes

Status	`detail`	When
`200`, `201`, `204`	none for `204`	Success. `201` for a new order, webhook or embed token; `204` for a deleted webhook.
`401`	`invalid token`	The token is missing, malformed, unknown or revoked. The response has `WWW-Authenticate: Bearer` and the same body in every case.
`403`	`arc_assist_off` or `assistant_off`	Only on the ask route: see Arc Assist.
`404`	`not found`	The member, webhook, or clinician does not exist, or belongs to another organization. The two cases are answered identically.
`409`	`endpoint limit reached` or `url already registered`	Registering a webhook.
`422`	a list, or a string	The body or parameters are not valid. Strings: `unknown panel '...'` for an order, `url must be ...` for a webhook address, and `invalid_input` for text the database cannot store (for example a NUL character).
`500`	`audit unavailable`	Protearc could not write the audit record of the request. Try again.
`503`	`unavailable`	Only on the ask route: the assistant could not answer right now.

A path that is not a route answers 404 with {"detail": "Not Found"}, and a wrong method on a route answers 405.