Error Reference

Every status code the API returns, what causes it, and how to recover — in one place.

Top 3 integration mistakes

⏰

Expired token

Tokens live 3600 s. Cache and refresh proactively — and remember a new token invalidates previously issued ones for your organization.

📅

Stale or date-less data

Follow the IFU freshness rules — labs within 90 days, vitals within 30 — and always send a valid ISO-8601 effectiveDateTime.

🔗

Missing fullUrl

Every bundle entry needs a unique fullUrl — it is how rejected entries are identified in rejectedItems.entryUrl.

HTTP status codes

Status	Meaning	Common causes	Resolution
200	Success	—	—
400	Bad request	Missing credentials fields · incomplete draft run (per-field `warnings`) · AI model errors (reported in `warnings`) · invalid test ID format	Fix the payload; on draft runs, resolve every entry in `warnings[]` first
401	Unauthorized	Invalid credentials · missing Bearer header · expired token (after 3600 s) · expired magic link	Re-authenticate and retry once with the new token
403	Forbidden	Test belongs to a different organization	Check you are using the ID returned to your org; do not retry
404	Not found	Unknown test ID · report requested before the test was run	Verify the GUID; run the test before requesting results/reports
500	Server error	Internal failure	contact support if persistent

Error shapes

Authentication endpoints return the ApiResponse envelope with status: "error" and per-field errors. CCS endpoints return a flat { "message": "…" }, with a warnings[] array on validation failures:

{
  "warnings": [
    "Age must be at least 18 years",
    "SystolicBloodPressure is required"
  ]
}

ℹ️ Note: AI-model failures surface the same way — a 400 whose warnings array contains "AI Model API Error: …". The draft remains intact and can simply be re-run.

Retries, rate limits & timeouts

401 — refresh the token (re-authenticate) and retry once. If it fails again, credentials are wrong — do not loop.

500 / network timeouts — retry with exponential backoff (e.g. 1 s → 2 s → 4 s, max 3 attempts). Draft creation is safe to retry; a duplicate draft is harmless and simply unused.

4xx other than 401 — a retry will fail identically; fix the request instead (exception: a 400 with "AI Model API Error" in warnings is retryable).

Volume — respect your organization's hourly call allowance (rateLimitPerHour); queue requests rather than hammering, and cache tokens instead of re-authenticating per call.

💡 Tip: Log the entryUrl values from rejectedItems — they carry the fullUrl of the exact FHIR entries your EHR export needs to fix.

Related pages: API Objects & Models · FAQ · Developer Quickstart — Questions? info@explorishealth.com

Error Reference

Top 3 integration mistakes#

HTTP status codes#

Error shapes#

Retries, rate limits & timeouts#

Top 3 integration mistakes

HTTP status codes

Error shapes

Retries, rate limits & timeouts