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.

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
`429 Too Many Requests`	`rate_limit_exceeded`	You’ve exceeded the rate limit. 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.

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. The X-Organization-Id header still requires a raw UUID.

Invalid header value:

{
  "code": "bad_request",
  "message": "'X-Organization-Id' must be a valid UUID",
  "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 not a valid UUID
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.

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

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

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

​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

Handling Errors in Code

Debugging