Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.medlistiq.com/llms.txt

Use this file to discover all available pages before exploring further.

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

CodeNameWhenHow to respond
200OKSuccessful inferenceParse body
401UnauthorizedMissing, invalid, or revoked API keyCheck your Authorization header — don’t retry until fixed
422Unprocessable EntityRequest body failed validation (e.g. both resources and bundle empty, or unknown format/verbosity value)Fix payload — don’t retry
429Too Many RequestsRate limit or monthly cap exceededRespect Retry-After; back off
503Service UnavailableTransient infra failure (rare — e.g. auth verification briefly unavailable during a deploy, or the OCR engine momentarily unreachable on the PDF endpoint)Retry with backoff

​
Shape

{ "detail": "missing API key" }

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

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

​
Common scenarios

You sent a request without an Authorization: Bearer ... header, or the key has been revoked. Generate a new one from the portal.
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.
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.
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).
Specific to POST /v1/med-lists/from-documents. We check that every upload starts with the %PDF- magic header before sending it downstream; a renamed .txt, .docx, or image triggers this. Rename and re-export as a real PDF, or drop the offending file from the request.
Specific to POST /v1/med-lists/from-documents. The per-request limits are 15 files, 50 MB per file, 150 MB total, and 200 pages combined after parsing. Split larger packets into multiple calls; server-side batching is on the roadmap. See Med lists from PDFs for the full list of validation messages.

​
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. For /v1/medications/infer, the same ID also appears inside the response body as meta.request_id. The PDF endpoint returns body-only and surfaces all metadata (request ID, page counts, processing time, ruleset version) via response headers — see Med lists from PDFs.