Skip to main content
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 parameters
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

​
Server Errors

StatusCodeDescription
500 Internal Server Errorinternal_errorSomething went wrong on our side. Retry the request or contact support.

​
Error Examples

​
401 — Invalid API Key

curl -X GET "https://api.maxcare.ai/v1/patients" \
  -H "Authorization: Bearer invalid_key" \
  -H "X-Organization-Id: org_abc123"

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

​
403 — Insufficient Scope

# API key doesn't have read:patients scope
curl -X GET "https://api.maxcare.ai/v1/patients" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: org_abc123"

{
  "code": "forbidden",
  "message": "Insufficient scope. Required: read:patients",
  "trace_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

​
404 — Resource Not Found

curl -X GET "https://api.maxcare.ai/v1/patients/nonexistent_id" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: org_abc123"

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

​
Handling Errors in Code

async function getPatient(apiKey, orgId, patientId) {
  const response = await fetch(
    `https://api.maxcare.ai/v1/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
      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