Errors

Every HTTP status code the API returns, when it fires, and how to respond.

Errors are returned as JSON with a detail field. Status-code semantics follow HTTP conventions — retry 5xx, don’t retry 4xx (except 429).

Status codes

Code	Name	When	How to respond
200	OK	Successful inference	Parse body
401	Unauthorized	Missing, invalid, or revoked API key	Check your Authorization header — don’t retry until fixed
422	Unprocessable Entity	Request body failed validation (e.g. both resources and bundle empty)	Fix payload — don’t retry
429	Too Many Requests	Rate limit or monthly cap exceeded	Respect Retry-After; back off
501	Not Implemented	format: "us_core" or format: "bundle" requested	Switch to format: "inferred_list" (default)
503	Service Unavailable	Transient infra failure (e.g. Clerk JWKS unreachable on /admin/*)	Retry with backoff

Shape

Simple errors (most)

{ "detail": "missing API key" }

Structured errors (rate/quota)

{
  "detail": {
    "error": "rate_limit_exceeded",
    "limit_per_minute": 60,
    "plan": "starter"
  }
}

Validation errors (Pydantic / FastAPI)

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body"],
      "msg": "request must include `resources` and/or `bundle`",
      "input": {}
    }
  ]
}

Common scenarios

401 — missing API key

You sent a request without an Authorization: Bearer ... header, or the key has been revoked. Generate a new one from the portal.

422 — request must include `resources` and/or `bundle`

You sent { "resources": [] } with nothing else. At least one of resources (non-empty array) or bundle (non-empty FHIR Bundle) must be present. See the Quickstart for a minimal working request.

429 — rate limit exceeded

You exceeded your plan’s per-minute limit. Back off for the number of seconds in the Retry-After header, then retry. If you’re hitting this often, consider upgrading to Starter or Pro.

429 — monthly cap reached

Your org has used all of its monthly request allowance. The upgrade_url in the response points to your billing page. Usage resets on the 1st of next month (UTC).

501 — output format not implemented

format: "us_core" and format: "bundle" are reserved for future use. Use the default format: "inferred_list" (or omit the field entirely).

Retries

For retryable errors (5xx, 429), use exponential backoff. Starting point:

• 429: respect Retry-After
• 503: 1s, 2s, 4s, 8s, then give up

Don’t retry 4xx other than 429 — they indicate the request itself is malformed and won’t succeed on retry.

Getting a request ID

Every response includes an x-request-id response header. If you open a support ticket, include that ID — we can trace the exact request in our logs.

The same ID also appears inside the response body as meta.request_id for successful /v1/* calls.