FHIR API error handling: retries, rate limits, and partial results.

Updated: 2026-08-25 · 10 min read

The bottom line

Retry only transient and safely repeatable work, honor server guidance, parse OperationOutcome when present, and expose partial sync state. An integration is more trustworthy when it reports incomplete data than when it silently returns an empty record.

Key takeaways

• A 200 empty search, a 403 scope denial, a 404 unsupported resource, and a timeout require different product states.
• Use exponential backoff with jitter and a retry budget; never create an unbounded retry loop.
• Persist per-source and per-category progress so one failed query does not erase successful data.

Evidence boundary: Uses FHIR R4 HTTP and OperationOutcome semantics with conservative distributed-systems retry practices.

Author: FinchNode Engineering

Start with an actionable error taxonomy

Use a bounded retry helper

export async function withRetry<T>(operation: () => Promise<T>, attempts = 4) {
  let lastError: unknown;
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;
      if (!isTransient(error) || attempt === attempts - 1) throw error;
      const base = Math.min(500 * 2 ** attempt, 8_000);
      const jitter = Math.floor(Math.random() * 250);
      await new Promise((resolve) => setTimeout(resolve, base + jitter));
    }
  }
  throw lastError;
}

Make partial synchronization visible

• Track status for each connection and record category.
• Return the latest successful data with its timestamp when policy permits stale reads.
• Include a machine-readable reason for unavailable or delayed categories.
• Emit lifecycle events when a connection requires user action.
• Never replace previously successful data with an unexplained empty snapshot after a failed refresh.

More FinchNode interoperability guides

• What we learned building patient-authorized FHIR connections across EHRs.
• SMART on FHIR OAuth with PKCE in React and Node.js.
• Fetch patient data with a FHIR API: Patient, labs, conditions, and medications.
• Epic and MyChart FHIR integration for patient-facing applications.
• Oracle Health FHIR integration: discovery, authorization, and tenant routing.
• How to normalize FHIR data across EHRs without losing the source.

Frequently asked questions