Integration best practices

• Always validate status_code and handle 429 (rate limit).
• Implement retry with exponential backoff for network failures.
• Store analysis_id in the medical record for auditing.
• Avoid logging sensitive patient data.
• Reuse results when the same set of medications is repeated.

Idempotency (Idempotency-Key)

To avoid duplicate analyses/charges on retries, send the Idempotency-Key header (a unique string per logical request, e.g. a UUID) on the POST endpoints: /interactions/check, /interactions/batch, /fhir/$check and /cds-services/{id}.

• Same key + same body → the original response is replayed from storage (response header Idempotent-Replayed: true); the analysis does not run again.
• Same key + different body → 409 Conflict (avoids returning the wrong result).
• The key is valid for 24h and is scoped per organization.

Transactional and billing semantics

The check response carries reconciliation metadata:

Field	Meaning
request_id	Correlates the request (also in the X-Request-Id header).
replayed_request	true when the response came from an idempotent replay.
billing_status	charged (analysis billed, incl. cache hit) · replayed (idempotent replay, not charged again).

Rules:

• An idempotent replay (Idempotent-Replayed: true) is not charged again (billing_status: "replayed").
• A cache response counts as an analysis (billing_status: "charged", cached: true).
• failed/partial responses keep the fail-safe contract; handle analysis_status first.
• Look up an analysis by id: GET /api/v1/analyses/{analysis_id}/status (status: complete | not_found), useful for reconciliation and retries.