Errors

All errors use a single, consistent shape — the Error Envelope. Error responses never include stack traces, datastore internals, plaintext secrets/tokens, or PHI values.


{
  "error": {
    "code": "CONSENT_REQUIRED",
    "message": "No active consent grant covers the requested scope."
  }
}

error.code — a non-empty, stable platform error code.
error.message — a non-empty, human-readable, leak-free message.
Some errors include extra safe fields (e.g. RATE_LIMITED adds retryAfterSeconds; INSUFFICIENT_SCOPE adds requiredScope).

⚠️

Always branch on error.code, not on the message text.

Error code reference

Code	HTTP	Trigger
`UNSUPPORTED_VERSION`	400	The request targets an API version that is not supported. Never rerouted to a different version.
`VALIDATION_ERROR`	400	Params/body fail validation, exceed the 1 MB body limit, exceed a field’s max length, or reuse an `Idempotency-Key` with a different body. No partial write.
`UNAUTHORIZED`	401	Missing, malformed, unknown, or revoked credential. Identical body across all such failures so client existence is never disclosed.
`TOKEN_EXPIRED`	401	The access token is recognized but expired. No data is returned.
`INSUFFICIENT_SCOPE`	403	The token lacks the endpoint’s required scope, or presents an undefined scope. Names the missing scope.
`CONSENT_REQUIRED`	403	No active, unexpired consent grant covers the client + user + scope.
`NOT_FOUND`	404	A resource does not exist, or exists but is not owned by the user. Both cases return an identical response.
`RATE_LIMITED`	429	Per-`clientId` (600/60s) or global IP limit exceeded. Includes `retryAfterSeconds`.
`ACCESS_NOT_RECORDED`	500	The audit entry for a PHI access could not be written, so the access is rejected.
`INTERNAL_ERROR`	500	An unexpected server error. No internal details exposed.

Recommended handling

Code	Suggested action
`TOKEN_EXPIRED`	Refresh the access token and retry once.
`CONSENT_REQUIRED`	Re-initiate the consent flow.
`INSUFFICIENT_SCOPE`	Request the missing scope in a new authorization.
`RATE_LIMITED`	Back off for `retryAfterSeconds` before retrying.
`VALIDATION_ERROR`	Fix the request; do not blindly retry.
`UNAUTHORIZED`	Re-authenticate; check your credentials.
`NOT_FOUND`	Treat as “no such accessible resource”.