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://docs.medblocks.com/errors/invalid_api_key",
    "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.

Envelope Fields

Field	Type	Description
`error.type`	`string`	Broad category such as `authentication_error`, `invalid_request_error`, or `ehr_error`.
`error.code`	`string`	Stable machine-readable code. Use this for branching.
`error.message`	`string`	Human-readable explanation for developers and logs.
`error.param`	`string` or `null`	Request field or parameter related to the error, when available.
`error.doc_url`	`string`	Documentation URL for the specific code.
`error.request_id`	`string`	Correlation ID. Include it in support tickets.

HTTP Statuses

Status	Meaning
`400`	Validation error, malformed request, or unsupported API version.
`401`	Missing, invalid, or expired API key.
`403`	API key is valid but does not have permission for the resource.
`404`	Resource was not found in your organization.
`409`	Resource conflict, such as a duplicate identifier.
`413`	Request payload is too large.
`429`	Rate limit or quota exceeded.
`500`	Unexpected Medblocks server error. Retry with backoff.
`502`	Upstream EHR, OAuth, email, token, or storage service failed.

Public Codes

Type	Code	Typical Cause
`authentication_error`	`not_authenticated`	The request is not authenticated.
`authentication_error`	`invalid_credentials`	Login or credential verification failed.
`authentication_error`	`session_expired`	A user session expired.
`authentication_error`	`missing_api_key`	`Authorization` header is missing.
`authentication_error`	`invalid_api_key`	API key is invalid.
`authentication_error`	`expired_api_key`	API key is expired.
`permission_error`	`forbidden`	Authenticated caller cannot access the operation.
`permission_error`	`org_access_denied`	Caller is not a member of the active organization.
`permission_error`	`role_insufficient`	User role is not allowed to perform the operation.
`permission_error`	`patient_access_denied`	Patient session is required or invalid.
`permission_error`	`scope_violation`	Resource is outside the active organization.
`permission_error`	`insufficient_scope`	API key lacks the required scope.
`invalid_request_error`	`bad_request`	Request is malformed or missing required fields.
`invalid_request_error`	`invalid_data`	Request data failed validation.
`invalid_request_error`	`payload_too_large`	Request body is too large.
`invalid_request_error`	`invalid_image`	Image data or format is invalid.
`invalid_request_error`	`unsupported_api_version`	`Version` header is not supported.
`invalid_request_error`	`oauth_state_expired`	OAuth state expired before callback completion.
`not_found_error`	`resource_not_found`	Patient, Session, or source was not found.
`conflict_error`	`resource_conflict`	Request conflicts with existing data.
`conflict_error`	`already_linked`	Resource is already linked to another entity.
`conflict_error`	`external_id_already_exists`	External identifier already exists in the organization.
`rate_limit_error`	`throttled`	Too many requests.
`rate_limit_error`	`quota_exceeded`	API key quota is exceeded.
`ehr_error`	`fhir_error`	Upstream FHIR service failed.
`ehr_error`	`oauth_error`	Upstream OAuth provider failed.
`ehr_error`	`email_error`	Email delivery failed.
`ehr_error`	`token_exchange_failed`	Medblocks could not exchange an OAuth code for tokens.
`ehr_error`	`token_unavailable`	No valid token is available for the upstream service.
`ehr_error`	`storage_error`	Cloud storage operation failed.
`api_error`	`internal_error`	Unexpected Medblocks server error.
`api_error`	`db_error`	Database operation failed.
`api_error`	`config_missing`	Required server configuration is missing.

Handling Pattern

try {
  await medblocks("/sessions", { method: "POST", body });
} catch (error) {
  if (error instanceof MedblocksError) {
    console.error("Medblocks API error", {
      status: error.status,
      code: error.body?.error?.code,
      requestId: error.body?.error?.request_id,
    });
  }

  throw error;
}

API Overview for authentication and versioning.
Picker Mode for hosted Session creation.
Direct Mode for source search and return URL handling.
Generated API Reference for exact endpoint schemas.

Envelope Fields

HTTP Statuses

Public Codes

Handling Pattern

Related Articles

On this page