BigMindBigMindBigMind
Partner API
Sign inGet an API key
Partner API
OverviewAuthenticationCustomersPlansQuotesAccount & UsageBackup statusWebhooksError codesChangelog

Error codes

All errors share the same envelope. Match on error.code (machine-readable) — error.message is for humans and may change between releases. Unless a description says otherwise, an error means nothing was written or charged.

CodeStatusWhen you'll see it
UNAUTHENTICATED401No API key on the request.
INVALID_API_KEY401API key is wrong, revoked, or the partner account is suspended or otherwise inactive.
PARTNER_READ_ONLY403Your partner account is expired: GET requests still work, every write is refused. Contact support to reactivate.
MIGRATION_IN_PROGRESS423Your account is being migrated from BigMIND 1.0. Writes are refused until it completes (`details.lockedAt`); reads work.
RATE_LIMITED429Exceeded 120 requests/minute — or a per-action cooldown: a welcome email resent within its window, the same event redelivered within a minute (details.reason). Wait per the Retry-After header.
ENDPOINT_RETIRED410The endpoint was removed. `details.useInstead` names its replacement; see the changelog.
TRIAL_EXPIRED403Partner trial expired. Cannot create new customers until upgraded.
CANNOT_SELL403Partner tier does not permit selling customers. Upgrade tier.
VALIDATION_FAILED400The body, a query parameter or the pagination failed validation, or the body is not JSON. details.details lists each problem with its path. Also: a test or redelivery on an inactive endpoint, a plan-change preview for a trial / free / BigMIND 1.0 customer (details.code), and 409 on reactivate when the renewal cannot be priced (details.reason COST_UNRESOLVED).
INSUFFICIENT_CREDITS402Your credit (or your distributor's account, `details.fundedBy`) is below the charge. `details.required`, `details.current` and, on create, a cost `breakdown`. Nothing was written.
DISTRIBUTOR_ACCOUNT_LIMIT400Your distributor's account cannot cover what BigMind charges it for this sale (its prepaid balance, or its post-paid credit limit). Nothing was written; contact your distributor.
CUSTOMER_NOT_FOUND404Customer ID does not exist or belongs to a different partner.
CUSTOMER_EXISTS409A customer with that email already exists under your partner account (also the answer when two creates of one address arrive at once).
CUSTOMER_DELETED_EMAIL_HELD409The address belongs to a customer you deleted whose data is kept. `details.releasable` says whether support can free it or a transfer is needed.
EMAIL_REGISTERED_AS_BIGMIND_USER409The address already has a direct BigMind account. It cannot become your customer.
EMAIL_REGISTERED_WITH_OTHER_PARTNER409The address is a customer of another partner.
CUSTOMER_CHANGED409Another request changed this customer while yours was being processed. Nothing was changed or charged; fetch the customer again and retry.
INVALID_PLAN404Not a plan you sell: unknown id, inactive, another partner's plan, or (on PATCH with billingCycle) a catalog plan not sold on that cycle.
PLAN_NOT_ENABLED400 / 403The plan exists but you cannot sell it: not priced (`details.action` configure_pricing), priced by a distributor who has not enabled it (contact_distributor), or 403 when your account is not enabled for the product (Home, Local DR, Vault) or the channel no longer sells it.
FREE_ACCOUNTS_DISCONTINUED400Free accounts are replaced by the free trial. Send `trial: true` instead.
EXTRA_WORKSPACES_NOT_SOLD400Extra workspaces are not sold: workspaces come with the plan (Standard 10, Pro unlimited). Send `addOns.extraWorkspaces` as 0; an existing count may only go down.
TRIAL_NOT_AVAILABLE400The plan has no free trial (DR-Only, Local DR, free, BigMIND 1.0).
TRIAL_ALREADY_USED409That mailbox already had a free trial, with any partner. +tags are collapsed (ann+x@ = ann@).
TRIAL_LIMIT_REACHED409You already have the most trials allowed running at once (25 by default).
ENDED_TRIAL_EXISTS409Only on installations that let an address sign up again: the address belongs to one of your customers whose free trial has ended. `details.customerId` names it; extend it, upgrade it or delete it, then create again.
TRIAL_EXTENSION_UNAVAILABLE403Extending a free trial is not offered on this installation.
TRIAL_NOT_EXTENDABLE409Only a free trial that has ended can be extended (`details.reason` NOT_ENDED), and not one closed because its address signed up again (CLOSED).
CAPACITY_EXCEEDED400The plan is too small for the customer: more users than it allows, or more data on a tier than it includes. `details.problems[]` has `kind` (users, hot, cold, deep_freeze), `used` and `limit`. Nothing was changed.
SEATS_BELOW_USAGE400Fewer users than the account has (legacy edit path).
PLAN_SEATS_FIXED400The plan comes with its own users (Home family plans); `seats` cannot be set on it. `details.reason` SEATS_CHANGED or TOO_MANY_MEMBERS.
CUSTOM_PLAN_ADDONS_FIXED400Your own plans carry their composition; per-customer `addOns` cannot be added on top. Edit the plan or move the customer.
CUSTOM_PLAN_BASE_MISSING400One of your plans is built on a base that no longer exists here. Contact support.
BM1_SUBSCRIPTION_IMMUTABLE400The customer is on a migrated BigMIND 1.0 plan: users, add-ons and cycle cannot change; move it to a BigMind plan (permanent).
BM1_PLAN_PAST_SUNSET
BM1_PLAN_HIDDEN_FROM_CUSTOMERS

BM1_PLAN_NO_WHOLESALE_PRICE

BM1_PLAN_NO_BILLING_PERIOD

BM1_PLAN_NO_DISTRIBUTOR_COST

BM1_PLAN_NO_RETAIL_PRICE
400 / 403A migrated BigMIND 1.0 plan that cannot be sold to a NEW customer, one code per reason.
USE_EDIT_DIALOG400Internal; never returned by the public API (PATCH applies the legacy rules itself).
FORBIDDEN400Operation not allowed for the customer's current state: suspending, reactivating or deleting an already deleted customer (`details.reason` CUSTOMER_DELETED), reactivating an ended trial or licence, changing a trial closed because its address signed up again (TRIAL_CLOSED). 403 on a DICOM report you did not attach.
AI_LENS_SALES_DISABLED403The call needs AI Lens, which is not sold through partners.
TAG_NOT_FOUND404A tag id that is not one of your tags (another partner's tag answers the same). On a create or PUT with tags, nothing was written.
TAG_LIMIT_REACHED400250 tags per partner, or 20 tags on one customer. `details.max` says which.
TAG_EXISTS409You already have a tag with that name (names are unique per partner; `details.tagId` is the existing one).
INVALID_SORT400`sortBy` or `sortDir` is not supported; `details.allowed` lists the sortable fields.
IDEMPOTENCY_KEY_REUSED422The Idempotency-Key was already used (within 24 hours) with a different request body. A new request takes a new key.
IDEMPOTENCY_IN_PROGRESS409The first request with this Idempotency-Key is still being processed. Retry after the Retry-After seconds; you then get its stored response.
WEBHOOK_NOT_FOUND404The webhook endpoint id does not exist or belongs to another partner.
WEBHOOK_LIMIT_REACHED400You already have 10 webhook endpoints. Delete one, or send several events to one endpoint.
INVALID_WEBHOOK_URL400The endpoint URL is refused: not http(s), a private, link-local or cloud-metadata address, a local hostname, or credentials in the URL. `details.reason` says which.
UNKNOWN_WEBHOOK_EVENT400An event name the platform never fires; `details.allowed` lists every event. Nothing was saved.
DELIVERY_NOT_FOUND404The delivery id is not on this endpoint (deliveries are kept for 30 days).
DEVICE_NOT_FOUND404The deviceId is not one of this customer's devices (or the device was deleted).
INVOICE_NOT_FOUND404The invoice id does not exist or belongs to another partner.
NOT_A_RESELLER404Statements exist for resellers only: your account is not under a distributor.
STORAGE_FULL402Customer storage quota exceeded. `details` includes `quotaGB`, `usedBytes`, `requiredBytes`.
KEY_REVOKED
PARTNER_INACTIVE
401Reserved; today both cases answer INVALID_API_KEY.
INTERNAL_ERROR500Unexpected server error. Safe to retry after a short delay.

How to read the response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Need 68.00 credits for this plan with add-ons.",
    "details": {
      "required": 68,
      "current": 12.5,
      "fundedBy": "partner",
      "breakdown": { "basePlanCost": 68, "addOnCost": 0, "total": 68 }
    }
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed",
    "details": {
      "details": [
        { "path": ["email"], "message": "Invalid email address", "code": "invalid_string" }
      ]
    }
  }
}