Error envelope

When a request fails, the CAIL Health API returns a non-2xx HTTP status and a JSON body describing the failure. Most errors share a common shape. A few categories of failure return a reduced shape, so a client should branch on the HTTP status code and read message, both of which are always available.

Standard error

The majority of errors use this shape:

1
{
2
  "statusCode": 404,
3
  "message": "Provider not found",
4
  "error": "Not Found",
5
  "meta": {
6
    "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98",
7
    "timestamp": "2026-05-15T10:30:45.000Z"
8
  }
9
}

Message

message is always present, and is either a single string or an array of strings.

For most failures it is a single human-readable string. For a request that fails field validation, it is an array with one entry per validation problem:

1
{
2
  "statusCode": 400,
3
  "message": [
4
    "latitude must not be less than -90",
5
    "latitude must not be greater than 90"
6
  ],
7
  "error": "Bad Request",
8
  "meta": {
9
    "requestId": "5e6f7a8b-9c0d-4123-a4b5-c6d7e8f9a0b1",
10
    "timestamp": "2026-05-15T10:30:45.000Z"
11
  }
12
}

Always handle message as either type.

Error code

Some failures add a code field: a short, machine-readable label for the specific failure. When present, code is the most precise signal to branch on.

1
{
2
  "statusCode": 409,
3
  "message": "Idempotency key reused with a different body.",
4
  "code": "conflict",
5
  "meta": {
6
    "requestId": "7e6f5d4c-3b2a-4190-bf8e-7d6c5b4a3f2e",
7
    "timestamp": "2026-05-15T10:30:45.000Z"
8
  }
9
}

code is not present on every error, and error may be absent when code is present. Treat both as optional.

Reduced shapes

Two categories of failure return fewer fields.

Pathway execution errors return only message and code, with no statusCode or meta. Read the HTTP status from the response itself:

1
{
2
  "message": "Pathway execution not found.",
3
  "code": "ExecutionNotFound"
4
}

An unexpected server error returns only statusCode and message:

1
{
2
  "statusCode": 500,
3
  "message": "Internal server error"
4
}

What to rely on

Field availability varies across these shapes, so build clients on the parts that do not vary:

• The HTTP status code of the response is always present and authoritative. Branch on it first.
• message is always present. Handle it as a string or an array of strings.
• code, error, and meta are best-effort. Use them when present, but never require them.

Support traceability

When meta.requestId is present, it uniquely identifies the request. Log it, and include it in any support request so the team can locate the request and its server-side context.