Error Handling

The Max AI API uses standard HTTP status codes and returns structured JSON error responses. Every error includes a machine-readable code, a human-readable message, and a trace_id for debugging.

Error Response Format

{
  "code": "not_found",
  "message": "Patient not found",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
`code`	string	Machine-readable error code (e.g., `unauthorized`, `forbidden`, `not_found`)
`message`	string	Human-readable description of the error
`trace_id`	string	Unique identifier for this request — include this when contacting support

HTTP Status Codes

Success

Status	Description
`200 OK`	Request succeeded. Response body contains the data.
`202 Accepted`	A live EHR read is still running. Poll the `Location` header (`GET /v4/ehr/reads/{readId}`) after `Retry-After` seconds.

Client Errors

Status	Code	Description
`400 Bad Request`	`bad_request`	The request is malformed or has invalid/missing parameters — see 400 details below
`401 Unauthorized`	`unauthorized`	Missing or invalid API key
`403 Forbidden`	`forbidden`	Valid API key but insufficient scope for this endpoint
`404 Not Found`	`not_found`	The requested resource doesn’t exist or isn’t accessible to your organization
`413 Payload Too Large`	`payload_too_large`	An uploaded file is larger than the endpoint accepts (25 MB for chart documents, 10 MB for insurance card and note images), or a file read live from the EHR is larger than 25 MB.
`422 Unprocessable Entity`	named	The request is well formed but the EHR’s current state refuses it. The `code` names the condition — see insurance and payer error codes, referring provider error codes and prescription error codes.
`429 Too Many Requests`	`rate_limit_exceeded`	You’ve exceeded the rate limit, or a live read exceeded your app’s share of the practice’s EHR rate. Check `Retry-After` or `X-RateLimit-Reset` headers.

Server Errors

Status	Code	Description
`500 Internal Server Error`	`internal_error`	Something went wrong on our side. Retry the request or contact support.
`501 Not Implemented`	`capability_unsupported`	The practice’s EHR does not offer this read. Decided before any EHR call; check `GET /v4/ehr/capabilities` and hide the feature instead of retrying.

Error Examples

400 — Validation Errors

The API returns 400 Bad Request when a required parameter is missing or has an invalid format. The message field tells you exactly which parameter is wrong: Missing required parameter:

{
  "code": "bad_request",
  "message": "'providerId' is required",
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Invalid ID format:

{
  "code": "bad_request",
  "message": "'id' must be a valid ID",
  "trace_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

In v3, resource IDs use a readable prefixed format (e.g., pat_c56103bcd39c46d39f3138dd2b5e05f6). The API accepts both prefixed IDs and raw UUIDs as path parameters. On every version, the X-Organization-Id header accepts org_… or a raw UUID.

Invalid header value:

{
  "code": "bad_request",
  "message": "'X-Organization-Id' must be a valid UUID or readable ID (e.g. pat_abc123def456...)",
  "trace_id": "c3d4e5f6-a7b8-9012-cdef-234567890123"
}

Common causes:

A required path or query parameter is missing from the request
An ID parameter contains an invalid value (e.g., not-a-uuid instead of a prefixed ID like pat_c56103bcd39c46d39f3138dd2b5e05f6 or a raw UUID like 550e8400-e29b-41d4-a716-446655440000)
The X-Organization-Id header is neither a raw UUID nor an org_… id
A comma-separated filter was supplied with no values — ?code= or ?code=, on /bills and /era-service-lines, ?status= on /bills and /claims. This is rejected rather than ignored, because dropping the filter would widen the response to every record in the organization instead of narrowing it. If your cohort is empty, omit the parameter (or skip the request entirely) rather than sending it blank:

{
  "code": "bad_request",
  "message": "code was supplied but names no values. Omit it to apply no filter, or pass a comma-separated list.",
  "trace_id": "d4e5f6a7-b8c9-0123-def0-345678901234"
}

401 — Invalid API Key

The message field varies depending on the specific authentication failure (invalid key, revoked key, missing header, etc.).

{
  "code": "unauthorized",
  "message": "Invalid or expired API key",
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

403 — Insufficient Scope

Returned when your API key is valid but lacks the required scope for the endpoint. The message tells you whether the key itself is missing the scope, or whether the scope is on the key but not granted by the organization’s installation.

{
  "code": "forbidden",
  "message": "Insufficient scopes. Required one of: [read:patients]. The API key is missing the required scope. Key scopes: [read:providers].",
  "trace_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

404 — Resource Not Found

curl -X GET "https://api.maxcare.ai/v3/patients/pat_d4f8e2a13b7c4e9fa6d21c5b8e3f7a90" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"

{
  "code": "not_found",
  "message": "Patient not found",
  "trace_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}

429 — Rate Limit Exceeded

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "d4e5f6a7-b8c9-0123-defg-234567890123"
}

The response includes headers to help you retry at the right time:

Header	Example	Description
`X-RateLimit-Limit`	`1000`	Max requests per window
`X-RateLimit-Remaining`	`0`	No requests left
`X-RateLimit-Reset`	`1774293714`	Unix timestamp when the window resets
`Retry-After`	`60`	Seconds to wait before retrying

See Rate Limits for retry strategies and best practices.

Insurance and payer error codes

Returned by POST /v4/patients/{id}/insurance:exact and POST /v4/payers. None of them wrote anything to the EHR.

Status	Code	Meaning
`422`	`payer_not_writable`	The `payerId` cannot be attached exactly; `data.reason` is `not_found_in_instance`, `inactive`, `no_integration_id` or `ehr_payer_missing`. Pick another payer from `GET /payers`.
`422`	`coverage_ranks_full`	Every coverage rank on the chart is taken. Staff must archive a policy in the EHR first; retrying will not help.
`409`	`coverage_rank_taken`	The request set `coverageOrder` and another policy already holds that rank. Staff must change the chart in the EHR.
`409`	`coverage_rank_out_of_order`	The request set `coverageOrder` but a lower rank is still free. Write the primary coverage first, then the secondary.
`422`	`directory_payer_not_found`	The EHR’s payer directory has no payer with that `directoryPayerId` and `name`. Use the values from `GET /payers/directory`.
`422`	`payer_inactive_in_ehr`	The practice has this payer but deactivated it. A biller must reactivate it in the EHR.
`503`	`ehr_unavailable`	`insurance:exact` and `POST /v4/patients/{id}/insurance` (not `/payers`): the request never reached the EHR, usually because another write to the same chart held it for longer than the platform waits. Retry with the same `Idempotency-Key`.

PATCH /v4/patients/{patientId}/insurance-policies/{policyId} answers 409 policy_update_refused when the EHR did not take the type change: it refused the save (for example, ModMed locks a policy that has claims) or still shows the previous type after it. Retrying will not help; check the policy in the EHR. GET /v4/payers?patientId= answers 404 patient_not_found when the patient is not in your organization. GET /v4/payers?newChart=true answers 400 for a primaryFacilityId outside your organization and 503 no_booking_identity when no live system connector can create the chart. An unknown instanceId is not an error: it returns an empty list.

Referring provider error codes

Returned by PUT /v4/patients/{id}/referring-provider. None of them wrote anything to the EHR.

Status	Code	Meaning
`422`	`npi_not_found`	The NPI is not in the national provider registry. Check the number; retrying will not help.
`422`	`chart_not_writable`	Refused before writing. `data.reason` is `practice_data_unreadable` (the chart’s form could not be read in full, so writing it would have blanked fields) or `directory_ambiguous` (EZDerm: the practice address book has too many providers with this last name to rule out an existing entry, so none was created). Set the provider in the EHR.
`503`	`ehr_unavailable`	The request never reached the EHR, usually because another write to the same chart or referring provider held it for longer than the platform waits. Retry with the same `Idempotency-Key`.

Prescription error codes

The prescription and pharmacy endpoints (v4, ModMed) return named codes so an app can branch without parsing prose. Codes marked (draft) or (send) come from POST /v4/prescriptions, /void and /send; see E-Prescribing.

Status	Code	Meaning
`400`	`capability_unsupported`	The patient’s EHR does not support this (prescriptions are ModMed only)
`404`	`patient_not_found`	No such patient in your organization
`404`	`prescription_not_found`	No such prescription in your organization, or the EHR no longer returns it
`502`	`ehr_unavailable`	The EHR could not be reached. Nothing was written; retry later.
`400`	`refills_exceed_max`	(draft) More refills than the drug schedule allows
`409`	`idempotency_conflict`	(draft) A request with this `Idempotency-Key` is still in flight
`409`	`ehr_write_uncertain`	(draft) The draft may have been created; `data.requiresReconciliation` is `true`. Check the chart before retrying.
`422`	`controlled_substance_unsupported`	(draft, send) Controlled substances are always refused
`422`	`prescriber_not_eligible`	(draft) The prescriber is not an eligible prescriber in this organization
`502`	`ehr_write_mismatch`	(draft) A draft was created but does not match the request; its id is in `data.prescriptionId`. The platform cannot void it; staff discard it in EMA.
`409`	`prescription_not_pending`	(draft, send) The prescription is not PENDING; `data.status` is its current status
`409`	`prescription_changed`	(send) The prescription changed between the checks and the send
`409`	`active_erx_elsewhere`	(send) The same drug was released to a different pharmacy within 90 days
`409`	`prescription_send_exists`	(send) The prescription already has a send in flight, unknown or submitted (`data.sendId`); it is never sent twice, whatever the key
`409`	`idempotency_key_reused`	(send) The key was already used for a different prescription or pharmacy; use a new key
`409`	`no_sending_identity`	(send) The user has no usable personal EHR login; `data.reason` is `none`, `not_live` or `no_session`. Call `maxcare.pickProvider()` and retry with the same key.
`401`	`authorizer_unverified`	(send, sync request, history refresh) `sessionToken` is invalid, expired, revoked or from another organization. Nothing was sent or requested.
`422`	`prescriber_not_erx_enabled`	(send) The prescriber has no Surescripts prescriber record
`422`	`erx_validation_failed`	(send) The EHR’s eRx validation returned errors (`data.errors`)
`422`	`pharmacy_validation_failed`	(send) The EHR’s pharmacy validation refused the target pharmacy
`422`	`pharmacy_not_erx_enabled`	(send) The target pharmacy does not accept new prescriptions electronically
`422`	`sig_too_long`	(send) The sig exceeds the pharmacy’s limit (`data.maxSigLength`)
`422`	`facility_conflict`	(send) The EHR reports a facility conflict for this prescription

Handling Errors in Code

async function getPatient(apiKey, orgId, patientId) {
  const response = await fetch(
    `https://api.maxcare.ai/v3/patients/${patientId}`,
    {
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "X-Organization-Id": orgId,
      },
    }
  );

  const json = await response.json();

  if (!response.ok) {
    switch (json.code) {
      case "unauthorized":
        throw new Error("API key is invalid. Check your credentials.");
      case "forbidden":
        throw new Error(`Missing scope: ${json.message}`);
      case "not_found":
        return null; // Patient doesn't exist
      case "rate_limit_exceeded":
        const resetAt = response.headers.get("X-RateLimit-Reset");
        const waitMs = resetAt ? parseInt(resetAt) * 1000 - Date.now() : 60_000;
        await new Promise((r) => setTimeout(r, Math.max(waitMs, 1000)));
        return getPatient(apiKey, orgId, patientId); // Retry once
      default:
        throw new Error(`API error (${json.code}): ${json.message}`);
    }
  }

  return json.data;
}

import time
import requests

def get_patient(api_key: str, org_id: str, patient_id: str):
    response = requests.get(
        f"https://api.maxcare.ai/v3/patients/{patient_id}",
        headers={
            "Authorization": f"Bearer {api_key}",
            "X-Organization-Id": org_id,
        },
    )

    data = response.json()

    if response.status_code == 401:
        raise Exception("API key is invalid. Check your credentials.")
    elif response.status_code == 403:
        raise Exception(f"Missing scope: {data['message']}")
    elif response.status_code == 404:
        return None  # Patient doesn't exist
    elif response.status_code == 429:
        reset_at = int(response.headers.get("X-RateLimit-Reset", 0))
        wait = max(reset_at - int(time.time()), 1)
        time.sleep(wait)
        return get_patient(api_key, org_id, patient_id)  # Retry once
    elif not response.ok:
        raise Exception(f"API error ({data['code']}): {data['message']}")

    return data["data"]

Debugging

If you encounter an unexpected error:

Check the trace_id in the error response
Verify your API key and Organization ID are correct
Confirm your app has the required scopes for the endpoint
Contact the Max AI team with the trace_id for further investigation

Overview

Core Concepts

Working with Appointments

Working with Patients

Prescriptions

Patient Tracking

Building Apps

Error Response Format

HTTP Status Codes

Success

Client Errors

Server Errors

Error Examples

400 — Validation Errors

401 — Invalid API Key

403 — Insufficient Scope

404 — Resource Not Found

429 — Rate Limit Exceeded

Insurance and payer error codes

Referring provider error codes

Prescription error codes

Handling Errors in Code

Debugging

​Error Response Format

​HTTP Status Codes

​Success

​Client Errors

​Server Errors

​Error Examples

​400 — Validation Errors

​401 — Invalid API Key

​403 — Insufficient Scope

​404 — Resource Not Found

​429 — Rate Limit Exceeded

​Insurance and payer error codes

​Referring provider error codes

​Prescription error codes

​Handling Errors in Code

​Debugging

Error Response Format

HTTP Status Codes

Success

Client Errors

Server Errors

Error Examples

400 — Validation Errors

401 — Invalid API Key

403 — Insufficient Scope

404 — Resource Not Found

429 — Rate Limit Exceeded

Insurance and payer error codes

Referring provider error codes

Prescription error codes

Handling Errors in Code

Debugging