Guides

Errors

Errors are RFC 9457 problem details with a stable machine-readable code.

Problem format

Any non-2xx response has content-type: application/problem+json. Branch on code, not on title or detail, which are for humans and may change.

typestringrequired
format: uri
titlestringrequired
statusintegerrequired
detailstringoptional
instancestringoptional
codestringrequired
Stable machine-readable error codes.
One of:VALIDATION_FAILEDUNAUTHENTICATEDTOKEN_EXPIREDTOKEN_INVALIDFORBIDDENNOT_FOUNDCONFLICTRATE_LIMITEDINTERNALFEATURE_NOT_IN_PLANPLAN_LIMIT_REACHEDSUBSCRIPTION_INACTIVEEMAIL_TAKENINVALID_CREDENTIALSREFRESH_TOKEN_INVALIDMEMBERSHIP_NOT_FOUNDMEMBER_EXISTSLAST_OWNERINVITATION_INVALIDINVITATION_EXPIREDWEAK_PASSWORDSTORE_NOT_FOUNDMARKETPLACE_NOT_CONFIGUREDSTORE_NOT_CONNECTEDSTORE_ALREADY_CONNECTEDCONNECTION_FAILEDWEBHOOK_SIGNATURE_INVALIDORDER_NOT_FOUNDHOST_NOT_FOUNDLIVE_SESSION_NOT_FOUNDLIVE_SESSION_OVERLAPLIVE_SESSION_INVALID_STATEATTENDANCE_ALREADY_OPENATTENDANCE_NOT_OPENRULE_NOT_FOUNDSUPPORT_REQUEST_NOT_FOUNDPAYOUT_NOT_FOUNDPAYOUT_INVALID_TRANSITIONHOST_NOT_LINKEDAUTH_TOKEN_INVALIDACTION_NOT_SUPPORTEDMARKETPLACE_ERRORAFTERSALE_NOT_FOUNDINVENTORY_ITEM_NOT_FOUNDINVENTORY_SKU_TAKENCONTACT_NOT_FOUNDAPI_KEY_INVALIDAPI_KEY_NOT_ALLOWEDAPI_SCOPE_MISSINGAPI_KEY_NOT_FOUNDWEBHOOK_NOT_FOUNDWEBHOOK_URL_INVALIDDELIVERY_NOT_FOUNDOAUTH_APP_NOT_FOUNDPLATFORM_ADMIN_REQUIREDDEVELOPER_ACCOUNT_RESTRICTEDDEVELOPER_ACCOUNT_REQUIREDINVALID_TRANSITIONOAUTH_INVALID_REQUESTOAUTH_APP_NOT_AVAILABLEINSTALLATION_NOT_FOUNDWEBHOOK_MANAGED_BY_APPASSIGNEE_NOT_MEMBERAI_QUOTA_EXCEEDEDAI_RATE_LIMITEDCREDIT_PACK_NOT_FOUNDVARIANT_MANAGEDNO_LABELSCHAT_NOT_CONNECTEDSHOP_MISMATCHCONVERSATION_NOT_FOUNDCHAT_CANNOT_SENDCHAT_AGENT_NOT_CONFIGUREDKNOWLEDGE_NOT_FOUNDQUICK_REPLY_NOT_FOUNDQUICK_REPLY_TAKENWAREHOUSE_NOT_FOUNDWAREHOUSE_ARCHIVEDWAREHOUSE_CODE_TAKENWAREHOUSE_IN_USEINSUFFICIENT_STOCKDUPLICATE_LINESSAME_WAREHOUSEINVENTORY_ITEM_IN_USESUPPLIER_NOT_FOUNDSUPPLIER_NAME_TAKENSUPPLIER_ARCHIVEDPURCHASE_ORDER_NOT_FOUNDPURCHASE_ORDER_STATERECEIVE_EXCEEDS_ORDEREDSTOCKTAKE_NOT_FOUNDSTOCKTAKE_STATESTOCKTAKE_IN_PROGRESSVARIANT_NOT_FOUNDVARIANT_ALREADY_LINKEDPLAN_NOT_FOUNDPLAN_UNCHANGEDINVOICE_NOT_FOUNDINVOICE_NOT_PAYABLEBILLING_NOT_CONFIGUREDPAYMENT_GATEWAY_ERRORSUBSCRIPTION_PAST_DUE
detailsobject (map)optional
errorsarray<object>optional
Field-level validation errors.
Show 2 child attributes
- pathstringrequired
- messagestringrequired
requestIdstringoptional

400 application/problem+json

{
  "type": "about:blank",
  "title": "Validation failed",
  "status": 400,
  "code": "VALIDATION_FAILED",
  "detail": "Request does not match the API contract",
  "instance": "/v1/orders?limit=500",
  "errors": [
    {
      "path": "/query/limit",
      "message": "must be <= 200"
    }
  ],
  "requestId": "6f1c2d3e-4b5a-4c6d-8e7f-90a1b2c3d4e5"
}

status repeats the HTTP status. details carries machine-readable context for some codes (e.g. details.required on API_SCOPE_MISSING, details.retryAfter on RATE_LIMITED).
errors lists field-level problems for VALIDATION_FAILED.
Quote requestId when contacting support.
Retry only 429 and 5xx. Other 4xx responses fail the same way until the request or the data changes.

Error codes

Codes from the ErrorCode enum of the contract (102 in total). The status column is typical; always read status.

Code	Status	Meaning
`VALIDATION_FAILED`	400 / 422	The request does not match the contract or a business rule; see `errors` and `detail`.
`UNAUTHENTICATED`	401	No bearer token was sent.
`TOKEN_EXPIRED`	401	Session access token expired (console sessions only).
`TOKEN_INVALID`	401	Session access token is invalid (console sessions only).
`FORBIDDEN`	403	The caller is not allowed to perform this action.
`NOT_FOUND`	404	The route or resource does not exist.
`CONFLICT`	409	The request conflicts with the current state.
`RATE_LIMITED`	429	Rate limit exceeded; wait `retry-after` seconds.
`INTERNAL`	500	Unexpected server error. Retry with backoff and quote `requestId` to support.
`FEATURE_NOT_IN_PLAN`	403	The tenant plan lacks the feature (API access requires Pro).
`PLAN_LIMIT_REACHED`	403	A plan quota (stores, members, ...) is used up.
`SUBSCRIPTION_INACTIVE`	403	The tenant subscription is not active.
`STORE_NOT_FOUND`	404	No store with this id in the tenant.
`MARKETPLACE_NOT_CONFIGURED`	409	The marketplace integration is not configured on the server.
`STORE_NOT_CONNECTED`	404	The store has no marketplace connection.
`ORDER_NOT_FOUND`	404	No order with this id in the tenant.
`ACTION_NOT_SUPPORTED`	409	The marketplace or the order state does not allow this action.
`MARKETPLACE_ERROR`	502	The marketplace rejected or failed the call; `detail` carries its message.
`AFTERSALE_NOT_FOUND`	404	No pending after-sales request with this id.
`INVENTORY_ITEM_NOT_FOUND`	404	No inventory item with this id.
`INVENTORY_SKU_TAKEN`	409	Another inventory item already uses this SKU.
`CONTACT_NOT_FOUND`	404	No contact with this id.
`API_KEY_INVALID`	401	The API key is unknown, revoked, expired, or its creator lost owner/admin access.
`API_KEY_NOT_ALLOWED`	403	The operation is not open to API keys.
`API_SCOPE_MISSING`	403	The key or app token has none of the scopes the operation requires.
`OAUTH_APP_NOT_FOUND`	404	No OAuth app with this id owned by the tenant.
`DEVELOPER_ACCOUNT_RESTRICTED`	403	Developer (sandbox) workspaces cannot connect stores, change plan, pay invoices, buy AI credits, or create API keys and manual webhook endpoints; they use OAuth apps.
`DEVELOPER_ACCOUNT_REQUIRED`	403	Third-party apps are created and submitted from a developer workspace in the Developer Console.
`OAUTH_INVALID_REQUEST`	400	Authorization request is invalid: unknown client_id, unregistered redirect_uri, or scopes beyond the app’s.
`OAUTH_APP_NOT_AVAILABLE`	403	The app is not published (only its developer tenant can authorize it) or is suspended.
`INSTALLATION_NOT_FOUND`	404	No active app installation with this id in the tenant.
`WEBHOOK_MANAGED_BY_APP`	409	The webhook endpoint belongs to an installed app; uninstall the app to remove it.
`VARIANT_MANAGED`	409	The variant follows a master item; change stock or price there.
`CHAT_NOT_CONNECTED`	409	Chat is not connected for this store.
`CONVERSATION_NOT_FOUND`	404	No conversation with this id.
`CHAT_CANNOT_SEND`	409	The marketplace does not allow a reply in this conversation now.
`WAREHOUSE_NOT_FOUND`	404	No warehouse with this id.
`WAREHOUSE_ARCHIVED`	409	The warehouse is archived.
`INSUFFICIENT_STOCK`	409	Not enough stock in the warehouse.
`VARIANT_NOT_FOUND`	404	No marketplace variant with this id.
`VARIANT_ALREADY_LINKED`	409	The variant is already linked to an inventory item.
`SUBSCRIPTION_PAST_DUE`	402	Writes are blocked until the outstanding invoice is paid.

Other codes in the enum are used by console-only features or are specific to one resource; their name describes the cause:

EMAIL_TAKENINVALID_CREDENTIALSREFRESH_TOKEN_INVALIDMEMBERSHIP_NOT_FOUNDMEMBER_EXISTSLAST_OWNERINVITATION_INVALIDINVITATION_EXPIREDWEAK_PASSWORDSTORE_ALREADY_CONNECTEDCONNECTION_FAILEDWEBHOOK_SIGNATURE_INVALIDHOST_NOT_FOUNDLIVE_SESSION_NOT_FOUNDLIVE_SESSION_OVERLAPLIVE_SESSION_INVALID_STATEATTENDANCE_ALREADY_OPENATTENDANCE_NOT_OPENRULE_NOT_FOUNDSUPPORT_REQUEST_NOT_FOUNDPAYOUT_NOT_FOUNDPAYOUT_INVALID_TRANSITIONHOST_NOT_LINKEDAUTH_TOKEN_INVALIDAPI_KEY_NOT_FOUNDWEBHOOK_NOT_FOUNDWEBHOOK_URL_INVALIDDELIVERY_NOT_FOUNDPLATFORM_ADMIN_REQUIREDINVALID_TRANSITIONASSIGNEE_NOT_MEMBERAI_QUOTA_EXCEEDEDAI_RATE_LIMITEDCREDIT_PACK_NOT_FOUNDNO_LABELSSHOP_MISMATCHCHAT_AGENT_NOT_CONFIGUREDKNOWLEDGE_NOT_FOUNDQUICK_REPLY_NOT_FOUNDQUICK_REPLY_TAKENWAREHOUSE_CODE_TAKENWAREHOUSE_IN_USEDUPLICATE_LINESSAME_WAREHOUSEINVENTORY_ITEM_IN_USESUPPLIER_NOT_FOUNDSUPPLIER_NAME_TAKENSUPPLIER_ARCHIVEDPURCHASE_ORDER_NOT_FOUNDPURCHASE_ORDER_STATERECEIVE_EXCEEDS_ORDEREDSTOCKTAKE_NOT_FOUNDSTOCKTAKE_STATESTOCKTAKE_IN_PROGRESSPLAN_NOT_FOUNDPLAN_UNCHANGEDINVOICE_NOT_FOUNDINVOICE_NOT_PAYABLEBILLING_NOT_CONFIGUREDPAYMENT_GATEWAY_ERROR

OAuth token endpoint errors

POST /v1/oauth/token and POST /v1/oauth/revoke answer in the RFC 6749 format { "error": "…", "error_description": "…" } instead of problem details. Branch on error.

error	Status	Meaning
`invalid_request`	400	A required parameter is missing.
`invalid_client`	401	Client authentication failed; sent with `www-authenticate: Basic`.
`invalid_grant`	400	Code or refresh token is unknown, expired, replayed, or no longer valid (app uninstalled); redirect_uri or code_verifier mismatch.
`unauthorized_client`	400	The app is suspended.
`unsupported_grant_type`	400	grant_type is not authorization_code or refresh_token.

See Build an app (OAuth 2.0) for how to handle them.