API Errors

Every non-2xx Platform API response returns the same envelope shape.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "API key invalid",
    "param": null,
    "doc_url": "https://medblocks.com/docs/reference/errors",
    "request_id": "9c9b6f7a-8e4f-4a3b-9c1e-6f3a2d8b7c4d"
  }
}

Log error.code, error.message, the HTTP status, and error.request_id. Show patients a friendly retry message instead of raw portal or OAuth text.

Error Fields

Every error carries the same fields. The wire envelope names them in snake_case under error, and the SDK exposes them as camelCase properties on the thrown MedblocksError. The values are identical, so branch on the same type and code either way.

HTTP Statuses

Error Codes

type is the broad category, code is the exact reason, and each row lists the HTTP status the response carries. Branch on code, the same string in the wire envelope and the SDK.

Handling Errors

The SDK throws a single MedblocksError for every failed request. Discriminate on err.type and err.code, the same strings the API returns. Use the isMedblocksError guard to tell an API error apart from a native or network failure, then re-throw what the guard rejects.

import { isMedblocksError } from "medblocks";

try {
  await mb.patientSession.init(input);
} catch (err) {
  if (!isMedblocksError(err)) throw err; // a native error, such as a network failure
  if (err.type === "authentication_error") {
    // 401, alert on a bad or expired key
  } else if (err.type === "invalid_request_error") {
    console.error("invalid", { param: err.param, code: err.code });
  } else if (err.type === "rate_limit_error") {
    // 429, wait err.retryAfter seconds
  } else {
    console.error("medblocks error", { code: err.code, requestId: err.requestId });
  }
}

A type this SDK version predates still arrives as a MedblocksError, so the final else catches it and a future category never slips past isMedblocksError. A transport failure that outlives the SDK’s retries is the exception. A dropped connection, a DNS failure, or a timeout surfaces as the runtime’s own error, such as a TypeError or an abort, not a MedblocksError, which is why the example re-throws it.

Log the request id on every error path. It’s the most useful field in a support ticket, because it lets us find your exact call.

import { isMedblocksError } from "medblocks";

catch (err) {
  if (isMedblocksError(err)) {
    logger.error("medblocks api error", {
      type: err.type,
      code: err.code,
      requestId: err.requestId,
      statusCode: err.statusCode,
      param: err.param,
    });
  }
  throw err;
}

MedblocksSignatureError is separate. It comes from webhook verification, never from an API call, and has no HTTP status. See Webhook Signature Errors.

Retries

The SDK retries transient failures for you before it throws. That covers rate limits (429), upstream errors (502, 503, 504), and network-level failures. It doesn’t retry other 4xx errors or 500, since retrying those won’t help. By the time an error reaches your catch, it has already been retried up to maxNetworkRetries times, three by default.

On a 429, the SDK honors the server’s Retry-After during its own retries. If those run out, the final MedblocksError still carries retryAfter for your own backoff.

Webhook Signature Errors

MedblocksSignatureError is not an API response error. Medblocks.webhooks.constructEvent throws it while verifying a webhook delivery, entirely client-side, so it has no HTTP status, no envelope, and no doc_url. Read err.reason to tell the failure modes apart, and return 400 on any of them.

The full reason table and a constructEvent handler live on the webhook signatures page.

Related Articles

• API Overview for authentication and versioning.
• Pagination for cursor paging on list endpoints.
• Medblocks-hosted page for the hosted patient session flow.
• Your own UI for source search and return URL handling.
• Generated API Reference for exact endpoint schemas.