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.
| 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 suspended or otherwise inactive. |
| PARTNER_READ_ONLY | 403 | Your partner account is expired: GET requests still work, every write is refused. Contact support to reactivate. |
| MIGRATION_IN_PROGRESS | 423 | Your account is being migrated from BigMIND 1.0. Writes are refused until it completes (`details.lockedAt`); reads work. |
| RATE_LIMITED | 429 | Exceeded 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_RETIRED | 410 | The endpoint was removed. `details.useInstead` names its replacement; see the changelog. |
| 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 | The 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_CREDITS | 402 | Your 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_LIMIT | 400 | Your 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_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 (also the answer when two creates of one address arrive at once). |
| CUSTOMER_DELETED_EMAIL_HELD | 409 | The 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_USER | 409 | The address already has a direct BigMind account. It cannot become your customer. |
| EMAIL_REGISTERED_WITH_OTHER_PARTNER | 409 | The address is a customer of another partner. |
| CUSTOMER_CHANGED | 409 | Another request changed this customer while yours was being processed. Nothing was changed or charged; fetch the customer again and retry. |
| INVALID_PLAN | 404 | Not 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_ENABLED | 400 / 403 | The 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_DISCONTINUED | 400 | Free accounts are replaced by the free trial. Send `trial: true` instead. |
| EXTRA_WORKSPACES_NOT_SOLD | 400 | Extra 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_AVAILABLE | 400 | The plan has no free trial (DR-Only, Local DR, free, BigMIND 1.0). |
| TRIAL_ALREADY_USED | 409 | That mailbox already had a free trial, with any partner. +tags are collapsed (ann+x@ = ann@). |
| TRIAL_LIMIT_REACHED | 409 | You already have the most trials allowed running at once (25 by default). |
| ENDED_TRIAL_EXISTS | 409 | Only 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_UNAVAILABLE | 403 | Extending a free trial is not offered on this installation. |
| TRIAL_NOT_EXTENDABLE | 409 | Only 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_EXCEEDED | 400 | The 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_USAGE | 400 | Fewer users than the account has (legacy edit path). |
| PLAN_SEATS_FIXED | 400 | The 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_FIXED | 400 | Your own plans carry their composition; per-customer `addOns` cannot be added on top. Edit the plan or move the customer. |
| CUSTOM_PLAN_BASE_MISSING | 400 | One of your plans is built on a base that no longer exists here. Contact support. |
| BM1_SUBSCRIPTION_IMMUTABLE | 400 | The 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 / 403 | A migrated BigMIND 1.0 plan that cannot be sold to a NEW customer, one code per reason. |
| USE_EDIT_DIALOG | 400 | Internal; never returned by the public API (PATCH applies the legacy rules itself). |
| FORBIDDEN | 400 | Operation 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_DISABLED | 403 | The call needs AI Lens, which is not sold through partners. |
| TAG_NOT_FOUND | 404 | A 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_REACHED | 400 | 250 tags per partner, or 20 tags on one customer. `details.max` says which. |
| TAG_EXISTS | 409 | You already have a tag with that name (names are unique per partner; `details.tagId` is the existing one). |
| INVALID_SORT | 400 | `sortBy` or `sortDir` is not supported; `details.allowed` lists the sortable fields. |
| IDEMPOTENCY_KEY_REUSED | 422 | The Idempotency-Key was already used (within 24 hours) with a different request body. A new request takes a new key. |
| IDEMPOTENCY_IN_PROGRESS | 409 | The first request with this Idempotency-Key is still being processed. Retry after the Retry-After seconds; you then get its stored response. |
| WEBHOOK_NOT_FOUND | 404 | The webhook endpoint id does not exist or belongs to another partner. |
| WEBHOOK_LIMIT_REACHED | 400 | You already have 10 webhook endpoints. Delete one, or send several events to one endpoint. |
| INVALID_WEBHOOK_URL | 400 | The 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_EVENT | 400 | An event name the platform never fires; `details.allowed` lists every event. Nothing was saved. |
| DELIVERY_NOT_FOUND | 404 | The delivery id is not on this endpoint (deliveries are kept for 30 days). |
| DEVICE_NOT_FOUND | 404 | The deviceId is not one of this customer's devices (or the device was deleted). |
| INVOICE_NOT_FOUND | 404 | The invoice id does not exist or belongs to another partner. |
| NOT_A_RESELLER | 404 | Statements exist for resellers only: your account is not under a distributor. |
| STORAGE_FULL | 402 | Customer storage quota exceeded. `details` includes `quotaGB`, `usedBytes`, `requiredBytes`. |
| KEY_REVOKED PARTNER_INACTIVE | 401 | Reserved; today both cases answer INVALID_API_KEY. |
| 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 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" }
]
}
}
}