Error codes

All errors share the same envelope. Match on error.code (machine-readable) — error.message is for humans and may change between releases.

Code	Status	When you'll see it
UNAUTHENTICATED	401	No API key on the request.
INVALID_API_KEY	401	API key is wrong, revoked, or the partner account is inactive.
RATE_LIMITED	429	Exceeded 120 requests/minute. Wait per the Retry-After header.
TRIAL_EXPIRED	403	Partner trial expired. Cannot create new customers until upgraded.
CANNOT_SELL	403	Partner tier does not permit selling customers. Upgrade tier.
VALIDATION_FAILED	400	Request body or query params failed validation. See `details` array for per-field errors.
INSUFFICIENT_CREDITS	400	Partner credits balance is below the required charge. `details` includes `required`, `current`, and (on create) a `breakdown`.
CUSTOMER_NOT_FOUND	404	Customer ID does not exist or belongs to a different partner.
CUSTOMER_EXISTS	409	A customer with that email already exists under your partner account.
INVALID_PLAN	404	Plan ID not found, inactive, or not enabled for this partner.
PLAN_NOT_ENABLED	400	Plan exists but is not enabled in your retail pricing, or required pricing setup is missing.
FORBIDDEN	400	Operation not allowed for the customer's current state (e.g., suspending a deleted customer, or partner trying to delete a user-uploaded file).
STUDY_NOT_FOUND	404	DICOM study UID not found in this customer, or not yet indexed in AI Lens. Returned identically for both — no cross-tenant info leak.
STORAGE_FULL	402	Customer storage quota exceeded. `details` includes `quotaGB`, `usedBytes`, `requiredBytes`.
FILE_TOO_LARGE	400	Uploaded report exceeds the 25 MB limit.
INVALID_REPORT_TYPE	400	Uploaded report must be PDF, DOC, DOCX, or TXT.
REPORT_NOT_FOUND	404	Report ID does not exist for this customer.
INTERNAL_ERROR	500	Unexpected server error. Safe to retry after a short delay.

How to read the response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Need 150.00 credits for this plan with add-ons.",
    "details": {
      "required": 150,
      "current": 50,
      "breakdown": {
        "basePlanCost": 100,
        "addOnCost": 50,
        "aiLensMedicalCost": 0,
        "total": 150
      }
    }
  }
}