Errors and asynchronous updates

Error format

Failed requests return an errors array. Each error has the HTTP status as a string, a short title and a detail message:

{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "detail": "Timezone is not a recognised IANA time zone."
    }
  ]
}

Use the HTTP status code to decide what to do; the detail text is for people and may change.

Status codes

Status	Meaning	What to do
`200 OK`	The read succeeded.
`201 Created`	The record was created. The response contains it.	Store its `id`.
`202 Accepted`	The update was accepted. See below.
`204 No Content`	The record was deleted.
`400 Bad Request`	The `X-Agency-Id` header is missing.	Add the header.
`401 Unauthorized`	The access token is missing, invalid or expired.	Check your token, or contact us for a new one.
`404 Not Found`	The record doesn't exist, or belongs to an agency that isn't yours or isn't the one in `X-Agency-Id`.	Check the ID and the header.
`422 Unprocessable Entity`	The request was well formed but a value was invalid, for example an unknown field or filter.	Fix the request using the `detail` message; retrying unchanged won't help.
`5xx`	Something went wrong on our side.	Retry later with backoff.

Asynchronous updates

Updates (PATCH and PUT) return 202 Accepted with the record as it stands. Some changes are applied in the background, so the response, or a read straight afterwards, may not reflect them yet. Read the record again shortly afterwards if you need to confirm the new values.

Assigning roles to a member also works in the background: Homecare Pro creates the member's tasks shortly after the request, so they may not appear in the task list immediately.

Creates return 201 Created with the new record, and deletes return 204 No Content.