Error Codes
Every API error returns a stable machine-readable code field. Branch your UI logic on code, not on message — codes are guaranteed stable across releases.
Error envelope:
{
"status": "failed",
"message": "Human-readable description",
"code": "MACHINE_READABLE_CODE"
}
Shop & API Key
These indicate a configuration problem. They should never be seen by real customers.
| Code | HTTP | Description | What to do |
|---|---|---|---|
SHOP_NOT_FOUND | 404 | API key references a deleted shop | Check your API key in the admin |
SHOP_UNDER_DEVELOPMENT | 403 | Shop is in maintenance mode | Show branded coming-soon page |
SHOP_BILLING_INVALID | 403 | Shop subscription has lapsed | Show branded coming-soon page |
DEV_MODE_DISABLED | 403 | Dev mode is turned off | Enable dev mode in Settings |
API_KEY_REQUIRED | 401 | x-api-key header not sent | Fix your request headers |
API_KEY_INVALID | 401 | API key does not exist | Check your key in the admin |
API_KEY_REVOKED | 403 | API key was deactivated | Create a new key |
ORIGIN_NOT_ALLOWED | 401 | Request origin not in the key's allowlist | Add your domain to the API key |
Products
| Code | HTTP | Description |
|---|---|---|
PRODUCT_NOT_FOUND | 404 | Product not found or has been unpublished |
PRODUCT_ID_REQUIRED | 422 | productId query param missing |
INVALID_VARIATION_KEY | 422 | variationKey format is invalid |
INVALID_OPTION_VALUES | 422 | Option value IDs in the variation key don't exist |
VARIANT_NOT_FOUND | 404 | The specific variation combination doesn't exist |
Categories
| Code | HTTP | Description |
|---|---|---|
CATEGORY_NOT_FOUND | 404 | Category not found or has been unpublished |
Search
| Code | HTTP | Description |
|---|---|---|
INVALID_SEARCH_QUERY | 422 | term query param missing or empty |
Coupons
| Code | HTTP | Description |
|---|---|---|
COUPON_CODE_REQUIRED | 422 | coupons array is empty |
COUPONS_DISABLED | 403 | Merchant has disabled the coupon module |
INVALID_SHIPPING_ID | 422 | Shipping ID provided is not valid |
COUPON_ZERO_TOTAL | 422 | Cannot apply coupon to a zero-total order |
INVALID_COUPON | 422 | Coupon code not found or conditions not met |
Orders
| Code | HTTP | Description |
|---|---|---|
ORDER_NOT_FOUND | 404 | Order not found or belongs to a different user |
ORDER_VALIDATION_FAILED | 422 | Order could not be validated (empty cart, etc.) |
DOWNLOAD_PRODUCT_NOT_FOUND | 404 | Product not found in the order |
DOWNLOAD_FILE_NOT_FOUND | 404 | File ID not found in the product |
DOWNLOAD_NOT_ACTIVE | 403 | Download has been disabled by the merchant |
DOWNLOAD_LIMIT_REACHED | 403 | Customer exceeded the allowed download count |
DOWNLOAD_EXPIRED | 403 | Download period has ended |
DOWNLOAD_FILE_MISSING | 500 | File not found on the server |
Customer Auth
| Code | HTTP | Description | What to do |
|---|---|---|---|
AUTH_NOT_INITIALIZED | 403 | Shop hasn't set up customer auth | Show "login unavailable" message |
EMAIL_REQUIRED | 422 | Email not provided | Validate form before submitting |
ACCOUNT_NOT_FOUND | 404 | No account with this email | Show "no account found" or offer to register |
ACCOUNT_BLACKLISTED | 403 | Account has been suspended | Show "contact support" message |
ACCOUNT_INACTIVE | 403 | Account is not active | Show "contact shop support" message |
TOO_MANY_LOGIN_ATTEMPTS | 429 | Rate limited on login attempts | Show "please wait" message |
TOO_MANY_VERIFY_ATTEMPTS | 429 | Rate limited on OTP attempts | Show "request a new code" message |
VERIFICATION_NOT_FOUND | 404 | OTP verification document not found | Ask customer to request a new code |
VERIFICATION_USER_MISMATCH | 422 | Email doesn't match the verification | Check the email field |
VERIFICATION_EVENT_MISMATCH | 422 | event field doesn't match | Use "login" for the event field |
VERIFICATION_NOT_VALID | 422 | Code has expired or already been used | Ask customer to request a new code |
INVALID_CODE | 422 | Incorrect OTP | Show "incorrect code, try again" |
GOOGLE_AUTH_REQUIRED | 403 | This account uses Google login | Offer Google login option |
EMAIL_ALREADY_EXISTS | 409 | Email taken during registration | Prompt to log in instead |
PHONE_NUMBER_INVALID | 422 | Phone number failed validation | Show inline validation error |
SESSION_EXPIRED | 401 | JWT token has expired | Clear token, redirect to login |
AUTH_TOKEN_MISSING | 401 | Authorization header not sent | Redirect to login |
AUTH_TOKEN_INVALID | 401 | Token could not be validated | Clear token, redirect to login |
AUTH_TOKEN_DEVICE_MISMATCH | 401 | Token was issued to a different device | Clear token, redirect to login |
AUTH_USER_NOT_FOUND | 404 | Authenticated user no longer exists | Clear token, redirect to login |
USER_NOT_FOUND | 404 | User lookup failed | Clear token, redirect to login |
INVALID_ACCESS_LINK | 422 | Magic link is invalid or already used | Show "this link is not valid" |
ACCESS_LINK_EXPIRED | 403 | Magic link has expired | Show "this link has expired" |
ORDER_CANCELLED | 403 | Order linked to magic link was cancelled | Show "this order was cancelled" |
ORDER_HAS_REFUND | 403 | Order linked to magic link has a refund | Reject silently or show "contact support" |
Reviews
| Code | HTTP | Description |
|---|---|---|
REVIEW_PRODUCT_NOT_FOUND | 404 | Product not found |
REVIEW_ORDER_NOT_FOUND | 404 | Order not found or not owned by user |
REVIEW_ORDER_STATUS_INVALID | 422 | Order must be delivered before a review can be submitted |
REVIEW_ALREADY_EXISTS | 409 | Customer already reviewed this order |
Newsletter
| Code | HTTP | Description |
|---|---|---|
EMAIL_ALREADY_SUBSCRIBED | 409 | Email is already subscribed |
NEWSLETTER_LIMIT_EXCEEDED | 403 | Shop's subscriber limit reached |
NEWSLETTER_RATE_LIMITED | 429 | Too many subscription attempts from this IP |
SUBSCRIPTION_NOT_VALID | 422 | Subscription document is invalid or expired |
SUBSCRIPTION_NOT_FOUND | 404 | Subscription not found |
Contact Form
| Code | HTTP | Description |
|---|---|---|
CONTACT_FORM_RATE_LIMITED | 429 | Too many submissions from this IP (limit: 3/hour) |
CONTACT_FORM_LIMIT_EXCEEDED | 403 | Shop's contact form submission limit reached |
Settings & Policies
| Code | HTTP | Description |
|---|---|---|
POLICY_NOT_FOUND | 404 | Policy type not configured by the merchant |
Config & Domain
| Code | HTTP | Description |
|---|---|---|
HOSTNAME_NOT_DETERMINED | 422 | Could not determine the request hostname |
DOMAIN_NOT_IDENTIFIED | 422 | Domain host not identified |
SHOP_ID_NOT_FOUND | 404 | Could not get shop ID from the domain |
SHOP_URL_INVALID | 422 | Shop URL is not valid |
Payments
| Code | HTTP | Description |
|---|---|---|
PAYMENTS_NOT_ENABLED | 403 | Online payments not configured for this shop |
PAYMENT_LINK_INVALID | 422 | Payment link is invalid or already used |
PAYMENT_LINK_EXPIRED | 403 | Payment link has expired |
INVOICE_NOT_FOUND | 404 | Invoice not found |
Notifications
| Code | HTTP | Description |
|---|---|---|
NOTIFICATION_NOT_FOUND | 404 | Notification not found or belongs to a different user |
Content
| Code | HTTP | Description |
|---|---|---|
CONTENT_MODEL_NOT_FOUND | 404 | Model slug doesn't exist in the admin |
CONTENT_ENTRY_NOT_FOUND | 404 | Entry not found or not published |
Analytics
| Code | HTTP | Description |
|---|---|---|
INVALID_USER_ID | 422 | userId field missing or invalid |
INVALID_SESSION_ID | 422 | sessionId field missing or invalid |
INVALID_EVENT | 422 | event field missing or invalid |