Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt

Use this file to discover all available pages before exploring further.

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"
}
FieldTypeDescription
codestringMachine-readable error code (e.g., unauthorized, forbidden, not_found)
messagestringHuman-readable description of the error
trace_idstringUnique identifier for this request — include this when contacting support

​
HTTP Status Codes

​
Success

StatusDescription
200 OKRequest succeeded. Response body contains the data.

​
Client Errors

StatusCodeDescription
400 Bad Requestbad_requestThe request is malformed or has invalid/missing parameters — see 400 details below
401 UnauthorizedunauthorizedMissing or invalid API key
403 ForbiddenforbiddenValid API key but insufficient scope for this endpoint
404 Not Foundnot_foundThe requested resource doesn’t exist or isn’t accessible to your organization
429 Too Many Requestsrate_limit_exceededYou’ve exceeded the rate limit. Check Retry-After or X-RateLimit-Reset headers.

​
Server Errors

StatusCodeDescription
500 Internal Server Errorinternal_errorSomething 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

​
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:
HeaderExampleDescription
X-RateLimit-Limit1000Max requests per window
X-RateLimit-Remaining0No requests left
X-RateLimit-Reset1774293714Unix timestamp when the window resets
Retry-After60Seconds 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;
}

​
Debugging

If you encounter an unexpected error:
  1. Check the trace_id in the error response
  2. Verify your API key and Organization ID are correct
  3. Confirm your app has the required scopes for the endpoint
  4. Contact the Max AI team with the trace_id for further investigation