Errors

Standard error shape

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid access token",
    "details": [],
    "request_id": "6a5d5b2d-2cf0-4b7f-a9e3-7f2c66d4c4c9"
  }
}

The details array is always present on the error envelope. It is an empty [] when no per-field context applies (e.g. 401 unauthorized, 404 not_found, 500 internal_error). When the failure is validation-related or spans multiple fields, each entry has the shape:

{
  "field": "weight_unit",
  "code": "invalid_value",
  "message": "Unknown unit. Accepted values: kg, lb."
}

• field: dotted path into the request body or the name of the offending query/header parameter.
• code: machine-readable failure reason (required, invalid_value, too_long, etc.).
• message: human-readable explanation.

The top-level error.code and error.message always describe the request as a whole; entries in details[] are the specific causes.

HTTP status codes

Error codes

The error.code field provides machine-readable error classification. Switch on this field rather than parsing the message.

Error examples

Error handling best practices

1. On 401, request a new token from your backend, then retry.
2. On 429, respect the Retry-After header; do not retry immediately.
3. On 502 / 503, retry with exponential backoff (recommended: 1s, 2s, 4s, 8s, max 3 retries).
4. On 409, the resource already exists; read the current state instead of retrying the create.
5. On 422, check the message for which field/value is invalid; this is a client-side fix.

Rate & token limits

Thrive AI Health enforces per-tenant request rate limits on every endpoint and per-tenant token quotas on endpoints that invoke LLMs (coaching chat, nudge generation, lab and workout analysis, insights). Both are tracked on the tenant; there is no separate user-level quota.

Concrete request and token limits are assigned per tenant during partner onboarding and communicated out-of-band. Read the RateLimit-* and TokenLimit-* response headers on every call to track remaining quota in-band.

# Quota remaining
RateLimit-Limit: 600
RateLimit-Remaining: 598
RateLimit-Reset: 1710601800

# Token quota remaining
TokenLimit-Limit: 60000
TokenLimit-Remaining: 59800
TokenLimit-Reset: 1710601800

# Overages return a Retry-After header
Retry-After: 12

On overage, the response body's error.type field is requests or tokens, indicating which quota was exhausted:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "type": "requests"
  }
}