Errors

HealthCloud uses conventional HTTP status codes. All error responses share a consistent JSON shape with a machine-readable code and a human-readable message.

Error Response Shape

404 Not Found404
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Patient with ID 'Patient/bad_id' not found.",
    "requestId": "req_01hx4f8gj3kqm9n",
    "docsUrl": "https://healthcloud.ai/docs/api/errors#NOT_FOUND",
    "details": {
      "resourceType": "Patient",
      "resourceId": "bad_id"
    }
  }
}

code — Machine-readable error type string. Use this in conditional logic.

message — Human-readable description of what went wrong.

requestId — Unique ID for this request. Include it when contacting support.

docsUrl — Direct link to documentation for this specific error code.

details — Optional structured context (FHIR issues, conflicting resource IDs, etc.).

HTTP Status Codes

StatusCodeDescription
400BAD_REQUESTThe request body or query parameters are malformed or missing required fields.
401UNAUTHORIZEDMissing, invalid, or expired API key or JWT token.
403FORBIDDENThe API key exists but lacks the required scope for this operation.
404NOT_FOUNDThe requested resource (patient, deployment, asset, etc.) does not exist.
409CONFLICTThe request conflicts with existing state (e.g. duplicate webhook URL).
422FHIR_VALIDATION_ERRORThe FHIR resource body failed R4 profile validation.
429RATE_LIMITEDToo many requests. See the Retry-After header for the backoff window.
500INTERNAL_ERRORAn unexpected server error occurred. The request ID can be shared with support.
503SERVICE_UNAVAILABLEA downstream dependency (EHR, lab) is temporarily unavailable.

Rate Limiting

Requests are rate-limited per API key. Default limits are 1,000 requests/minute for standard plans. The response includes headers showing your current limit window.

429 Too Many Requests429
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1742558400

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "requestId": "req_ratelimit_abc"
  }
}

FHIR Validation Errors

When submitting FHIR resources, the API validates against R4 profiles. Validation errors are returned as structured issue arrays inside details.issues.

422 FHIR Validation Error422
{
  "error": {
    "code": "FHIR_VALIDATION_ERROR",
    "message": "FHIR R4 validation failed for Observation resource.",
    "requestId": "req_fhir_xyz",
    "details": {
      "issues": [
        {
          "severity": "error",
          "code": "required",
          "path": "Observation.status",
          "diagnostics": "Observation.status is required but missing."
        },
        {
          "severity": "error",
          "code": "value",
          "path": "Observation.code",
          "diagnostics": "Observation.code must use a LOINC coding system."
        }
      ]
    }
  }
}

Retry Logic

Retry 429 and 5xx errors with exponential backoff. The SDK handles this automatically; the example below shows manual implementation for raw HTTP clients.

import healthcloud as hc
import time

MAX_RETRIES = 4

def fetch_with_retry(fn, *args, **kwargs):
    for attempt in range(MAX_RETRIES):
        try:
            return fn(*args, **kwargs)
        except hc.RateLimitError as e:
            if attempt < MAX_RETRIES - 1:
                time.sleep(e.retry_after)
            else:
                raise
        except hc.InternalServerError:
            if attempt < MAX_RETRIES - 1:
                time.sleep(2 ** attempt)  # exponential backoff
            else:
                raise

patients = fetch_with_retry(hc.patients.list)

Still stuck?

Include your requestId when contacting support.

Contact Support