Errors

Resource methods throw AffinityError for unsuccessful API responses. Inspect its code, status, request ID, and field-level issues.

import { AffinityError } from "@affinity-health/sdk";

try {
  await affinity.forPractice(practiceId).orders.get("ord_...");
} catch (error) {
  if (error instanceof AffinityError) {
    // Safe metadata for support; avoid logging clinical response bodies.
    console.error(error.code, error.status, error.requestId);
  }
  throw error;
}

Each problem type links to the API error-code catalog. Use its recovery guidance when handling a specific code.

Clinical validation

Signing can return HTTP 422 with code: "clinical_requirements_unmet". Read error.problem?.data?.issues for field-level issues. Each issue includes code, path, and message; signing issues also identify the affected prescription and pharmacy. The problem’s data property is extensible, so check its shape before using it.

// Inside an AffinityError handler:
if (error.code === "clinical_requirements_unmet") {
  const issues = error.problem?.data?.issues;
  if (Array.isArray(issues)) {
    for (const issue of issues) {
      if (typeof issue?.path === "string" && typeof issue?.message === "string") {
        // Display issue.message beside the field identified by issue.path.
      }
    }
  }
}

Correct the clinical information, review the new prescription version, and sign again. Retrying an unchanged request will not resolve a validation error. See pharmacy clinical requirements for the preview response and explicit review statuses.

Patient information conflicts

Signing returns HTTP 409 with code: "conflict" and an issue code of patient_information_required when the patient allergy review is incomplete, the allergy history has changed since the draft was prepared, or required contact information is missing. Read problem.data.issues for the affected path and message. Open your allergy-review or patient contact form, save the corrected information, then review and sign the current prescription versions. An unreviewed allergy history must never be treated as no known allergies.

This readiness check precedes the pharmacy-specific 422 clinical validation above. Handle both codes; retrying without correcting the patient record will fail again.

Transport errors

Network and timeout failures can be native Fetch or abort errors. Use AffinityError.retryable for API response failures. A retryable response still requires the same persisted key and unchanged input for consequential actions.

Do not log response bodies that can contain protected health information.