# Billing & Plans

Plan tiers, patient quota, and how paid features are enabled per workspace.

Medblocks Connect has two plans.

| Plan           | Price          | Patient limit         | Notable features                                                                                                                   |
| -------------- | -------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Free**       | $0             | 1,000 active patients | Patient-mediated exchange, synthetic sandboxes, full API access, wearable device sync, export destinations, custom EHR client IDs. |
| **Enterprise** | $60,000 / year | Uncapped              | Everything in Free, plus Backend Services, Clinical Workflows, OCR, and data structuring.                                          |

Contact `support@medblocks.com` to upgrade your plan.

## Patient quota [#patient-quota]

The Free plan includes 1,000 active patients. A patient counts as “active” the first time we successfully pull FHIR data for them, so simply creating a patient record does not draw against the quota.

## Handling `billing_error` in your code [#handling-billing_error-in-your-code]

Requests that the workspace’s plan doesn’t cover come back with HTTP `402` and `error.type = "billing_error"`. The credentials are valid, the workspace just needs an upgrade. Catch the error and surface an upgrade CTA in your UI, or point the user at Medblocks support.

```ts
try {
  await medblocks("/webhooks", { method: "POST", body });
} catch (error) {
  if (error instanceof MedblocksError && error.body?.error?.type === "billing_error") {
    showUpgradeDialog();
    return;
  }
  throw error;
}
```

## Common errors [#common-errors]

Every `billing_error` uses the shared envelope described in [API Errors](/docs/reference/errors). Two codes cover the two situations, and clients should branch on `error.code`.

The `feature_not_enabled` code fires when the workspace’s plan doesn’t include the requested feature.

```json
{
  "error": {
    "type": "billing_error",
    "code": "feature_not_enabled",
    "message": "This feature isn't part of your plan. Contact support to enable it.",
    "param": null,
    "doc_url": "https://medblocks.com/docs/reference/errors",
    "request_id": "9c9b6f7a-8e4f-4a3b-9c1e-6f3a2d8b7c4d"
  }
}
```

The `quota_exceeded` code fires when a Free-tier workspace has hit its active-patient limit and a new patient tries to sync.

```json
{
  "error": {
    "type": "billing_error",
    "code": "quota_exceeded",
    "message": "You've hit your patient limit. Contact support to increase it.",
    "param": null,
    "doc_url": "https://medblocks.com/docs/reference/errors",
    "request_id": "9c9b6f7a-8e4f-4a3b-9c1e-6f3a2d8b7c4d"
  }
}
```

The full status-code catalog and envelope reference lives in [API Errors](/docs/reference/errors).

## Need help?

Running into an issue or have a question the docs do not answer? Get support from the Medblocks team through https://forms.gle/dtVxkmfL6Yimp6SBA and we will get back to you.