Errors

The API uses standard HTTP status codes. Errors return an RFC 9457 problem details body with Content-Type: application/problem+json:

{
  "type": "https://docs.theahealth.com/concepts/errors/#validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "1 field is invalid.",
  "instance": "/api/partner/v1/cases",
  "request_id": "req_8c41f0e2d7b9",
  "errors": [
    { "field": "patient.date_of_birth", "message": "Must be a date in YYYY-MM-DD format." }
  ]
}

Field	Meaning
type	Identifies the kind of error. Branch on this, not on title or detail. It links to the entry below.
title	A short, fixed summary of the error type.
status	The HTTP status code, repeated.
detail	What went wrong in this request, for logs and debugging. Wording can change.
instance	The request path.
request_id	Unique per request, also sent as the X-Request-Id header. Include it when you contact support.
errors	For validation-error, consent-required, and provider-not-active only: one entry per invalid field.

Retrying

Status	Retry?
400, 401, 403, 404, 409, 413, 422	No. Fix the request first.
429	Yes, after the Retry-After header’s number of seconds.
500, 502, 503, 504, network errors	Yes, with exponential backoff. Send the same Idempotency-Key so a retried write is never applied twice.

Tip

Use an Idempotency-Key on every POST. It makes retrying after a timeout or 5xx safe.

Error catalog

malformed-request

400. The body isn’t valid JSON, or the Content-Type isn’t application/json (multipart/form-data for POST /cases/{case_id}/files). Check your serialization.

unauthenticated

401. The Authorization header is missing, isn’t a bearer token, or the partner key is invalid, revoked, expired, or for the other environment. Check which key and base URL you’re using.

invalid-practice-key

401. The request needs a Thea-Practice-Key header, and it’s missing, malformed, from the other environment, or was issued to a different partner. See Authentication.

invalid-grant

400. The connect code is invalid, expired, already used, or was issued for a different redirect_uri. Send the practice admin through the connect flow again.

insufficient-scope

403. The key can access the practice but lacks a scope this operation needs. detail names the missing scope. See scopes.

practice-not-connected

403. The practice disconnected from your organization, so its practice key no longer works. Stop offering eConsults for it. See Practices and connections.

practice-mismatch

403. A practice_id in the path or body isn’t the practice your practice key belongs to. Check that you’re pairing each practice with its own key.

baa-required

403. A live key was used before a Business Associate Agreement between your organization and Thea took effect. Contact support@theahealth.com.

not-found

404. The resource doesn’t exist, or it belongs to a different practice than your practice key. The two cases are deliberately indistinguishable.

idempotency-key-reused

409. The Idempotency-Key was already used in the last 24 hours with a different request. Use a new key for each distinct request. See Idempotency.

case-closed

409. You tried to post a message or upload a file on a closed case. Reopen it with POST /cases/{case_id}/reopen first.

file-too-large

413. The file is over 25 MB. Compress or split it, then upload again.

validation-error

422. The request is well-formed but some fields are invalid: a required field is missing, a value has the wrong type or format, or a referenced ID (such as a specialty_id or provider) doesn’t exist, or an uploaded file isn’t a supported type. Each problem is listed in errors.

provider-not-active

422. The provider on a new case isn’t an active provider in the practice, for example because their seat was removed. Tell the clinician and offer another way to send. See Providers and seats.

consent-required

422. patient_consent_given wasn’t true when creating a case. Thea only accepts eConsults the patient has agreed to.

rate-limited

429. The practice, or your partner-key-only traffic, went over its rate limit. Wait for the number of seconds in Retry-After, then retry.

internal-error

500. Something went wrong on Thea’s side. Retry with backoff and the same Idempotency-Key. If it continues, contact support with the request_id.