Error Codes

Every failed request carries a code: a stable, machine-readable identifier for what went wrong. This page lists them all.

{
  "success": false,
  "message": "The request contains invalid parameters",
  "code": "ValidationError",
  "data": null
}

For the response envelope itself, validation errors and HTTP status codes, see Responses & Errors.

Error Codes Reference

Authentication & Authorization

AccessDenied

HTTP Status: 403 ForbiddenDescription: You don’t have permission to access this resource or perform this action.Common causes:

API key lacks required scope
Trying to access another user’s resources
Account restrictions or suspensions
Store-level permissions insufficient

How to fix:

Check your API key has the necessary scopes
Verify you’re accessing resources you own
Check account status in dashboard
Request additional permissions if needed

Example:

{
  "success": false,
  "message": "Your API key does not have permission to update products",
  "code": "AccessDenied",
  "data": null
}

BadToken

HTTP Status: 401 UnauthorizedDescription: The provided authentication token is invalid, expired, or malformed.Common causes:

Expired API key
Revoked API key
Malformed Authorization header
API key not found

How to fix:

Generate a new API key from dashboard
Verify Authorization header format: Bearer YOUR_API_KEY
Check for whitespace or special characters in token
Ensure API key hasn’t been revoked

Example:

{
  "success": false,
  "message": "The provided API key is invalid or has expired",
  "code": "BadToken",
  "data": null
}

TwoFactorRequired

HTTP Status: 403 ForbiddenDescription: Two-factor authentication is required for this action.Common causes:

Sensitive operation requires 2FA
Account security policy enforced
Administrative action attempted

How to fix:

Complete 2FA challenge
Enable 2FA on your account
Use session-based authentication for sensitive operations

Example:

{
  "success": false,
  "message": "This operation requires two-factor authentication",
  "code": "TwoFactorRequired",
  "data": null
}

OAuthLoginRequired

HTTP Status: 401 UnauthorizedDescription: OAuth authentication is required for this endpoint.Common causes:

Endpoint requires user session, not API key
OAuth flow not completed
Session expired

How to fix:

Complete OAuth authentication flow
Use correct authentication method for endpoint
Check if endpoint supports API key authentication

Example:

{
  "success": false,
  "message": "This endpoint requires OAuth authentication",
  "code": "OAuthLoginRequired",
  "data": null
}

Validation & Input Errors

ValidationError

HTTP Status: 400 Bad RequestDescription: The request contains invalid or missing parameters.Common causes:

Missing required fields
Invalid data types
Values outside allowed ranges
Invalid format (email, URL, UUID, etc.)
Business rule violations

How to fix:

Check request body against API documentation
Validate data types and formats
Ensure all required fields are present
Review error details for specific field errors

Example:

{
  "success": false,
  "message": "Price must be greater than 0",
  "code": "ValidationError",
  "data": null
}

BadCaptcha

HTTP Status: 400 Bad RequestDescription: CAPTCHA verification failed.Common causes:

Invalid CAPTCHA response
Expired CAPTCHA token
CAPTCHA not solved
Bot detection triggered

How to fix:

Request new CAPTCHA challenge
Ensure user completes CAPTCHA
Check CAPTCHA token hasn’t expired
Verify CAPTCHA integration is correct

Example:

{
  "success": false,
  "message": "CAPTCHA verification failed. Please try again.",
  "code": "BadCaptcha",
  "data": null
}

Resource Errors

NotFound

HTTP Status: 404 Not FoundDescription: The requested resource does not exist.Common causes:

Invalid resource ID
Resource was deleted
Typo in endpoint URL
Resource belongs to different store

How to fix:

Verify resource ID is correct
Check resource hasn’t been deleted
Ensure you’re querying the right store
Validate endpoint URL

Example:

{
  "success": false,
  "message": "Product not found",
  "code": "NotFound",
  "data": null
}

ObjectConflict

HTTP Status: 409 ConflictDescription: The operation conflicts with an existing resource.Common causes:

Duplicate unique field (email, slug, etc.)
Resource already exists
Concurrent modification conflict
Business rule prevents operation

How to fix:

Use unique values for unique fields
Check if resource already exists
Implement optimistic locking for concurrent updates
Review business rules

Example:

{
  "success": false,
  "message": "A product with this slug already exists",
  "code": "ObjectConflict",
  "data": null
}

Rate Limiting

RateLimited

HTTP Status: 429 Too Many RequestsDescription: You have exceeded the API rate limit.Common causes:

Too many requests in short time period
Burst limit exceeded
Account-level rate limit reached

How to fix:

Implement exponential backoff
Respect Retry-After header
Cache frequently accessed data
Optimize API calls to reduce frequency
Contact support for higher limits

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1638360000
Retry-After: 60

Example:

{
  "success": false,
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "code": "RateLimited",
  "data": null
}

Business Logic Errors

ProductUnavailable

HTTP Status: 400 Bad RequestDescription: The requested product is not available for purchase.Common causes:

Product out of stock
Product is private or unlisted
Product deleted or disabled
Product not available in customer’s region
Purchase limits exceeded

How to fix:

Check product availability
Verify product stock levels
Ensure product is public
Check regional restrictions

Example:

{
  "success": false,
  "message": "This product is currently out of stock",
  "code": "ProductUnavailable",
  "data": null
}

NotEnoughFunds

HTTP Status: 400 Bad RequestDescription: Insufficient funds in customer balance.Common causes:

Customer balance too low
Attempting to use balance payment method
Withdrawal amount exceeds available balance

How to fix:

Check customer balance
Request customer add funds
Use alternative payment method
Reduce order amount

Example:

{
  "success": false,
  "message": "Insufficient customer balance",
  "code": "NotEnoughFunds",
  "data": null
}

VerificationRequired

HTTP Status: 403 ForbiddenDescription: Account verification is required before proceeding.Common causes:

Email not verified
Identity verification pending
Payment method requires verification
Account limits require verification

How to fix:

Complete email verification
Submit required verification documents
Verify payment methods
Contact support for verification status

Example:

{
  "success": false,
  "message": "Email verification required",
  "code": "VerificationRequired",
  "data": null
}

Feature & Upgrade Errors

FeatureUnavailable

HTTP Status: 403 ForbiddenDescription: This feature is not available for your account.Common causes:

Feature disabled for your plan
Beta feature not enabled
Regional restrictions
Feature requires specific integration

How to fix:

Check feature availability for your plan
Contact support to enable beta features
Verify regional availability
Review feature requirements

Example:

{
  "success": false,
  "message": "Advanced analytics is not available on your current plan",
  "code": "FeatureUnavailable",
  "data": null
}

UpgradeRequired

HTTP Status: 402 Payment RequiredDescription: Your current plan does not support this operation.Common causes:

Plan limits exceeded
Feature requires higher plan tier
Usage quota exhausted

How to fix:

Upgrade to higher plan tier
Review current plan limits
Reduce usage to stay within limits
Contact sales for enterprise options

Example:

{
  "success": false,
  "message": "You have reached the maximum number of products for your plan",
  "code": "UpgradeRequired",
  "data": null
}

UnsupportedRequest

HTTP Status: 400 Bad RequestDescription: The requested operation is not supported.Common causes:

Deprecated API version
Invalid operation combination
Unsupported payment method
Unsupported currency

How to fix:

Check API documentation for supported operations
Use current API version
Verify operation compatibility
Check supported payment methods/currencies

Example:

{
  "success": false,
  "message": "This payment method is not supported for subscriptions",
  "code": "UnsupportedRequest",
  "data": null
}

File & Upload Errors

UploadFailed

HTTP Status: 400 Bad RequestDescription: File upload failed.Common causes:

File too large
Invalid file type
Corrupted file
Network interruption
Storage quota exceeded

How to fix:

Check file size limits
Verify file type is supported
Ensure file is not corrupted
Retry upload with stable connection
Check storage quota

Example:

{
  "success": false,
  "message": "File size exceeds maximum allowed size",
  "code": "UploadFailed",
  "data": null
}

Server Errors

InternalServerError

HTTP Status: 500 Internal Server ErrorDescription: An unexpected error occurred on the server.Common causes:

Server-side bug
Database connection issue
External service failure
Unexpected condition

How to fix:

Retry the request after a short delay
If problem persists, contact support
Check status page for incidents
Include error ID when contacting support

Example:

{
  "success": false,
  "message": "An unexpected error occurred",
  "code": "InternalServerError",
  "data": null
}

Always include the errorId when reporting issues to support for faster resolution.

HTTP Status Code Summary

Status Code	Error Codes	Description
400	ValidationError, BadCaptcha, ProductUnavailable, NotEnoughFunds, UnsupportedRequest, UploadFailed	Bad Request - Invalid input
401	BadToken, OAuthLoginRequired	Unauthorized - Invalid or missing authentication
402	UpgradeRequired	Payment Required - Plan upgrade needed
403	AccessDenied, TwoFactorRequired, VerificationRequired, FeatureUnavailable	Forbidden - Insufficient permissions
404	NotFound	Not Found - Resource doesn’t exist
409	ObjectConflict	Conflict - Resource conflict
429	RateLimited	Too Many Requests - Rate limit exceeded
500	InternalServerError	Internal Server Error - Server-side issue

Support Resources

System Status

Check API and service status

Help Center

Browse error troubleshooting guides

Discord Community

Get help from the community

Contact Support

Report issues with error IDs

API Documentation

Reference

OAuth2

User

Stores

Products

Categories

Variants

Coupons

Tickets

Customers

Orders

Reviews

Affiliates

Webhooks

Error Codes Reference

Authentication & Authorization

Validation & Input Errors

Resource Errors

Rate Limiting

Business Logic Errors

Feature & Upgrade Errors

File & Upload Errors

Server Errors

HTTP Status Code Summary

Support Resources

System Status

Help Center

Discord Community

Contact Support

​Error Codes Reference

​Authentication & Authorization

​Validation & Input Errors

​Resource Errors

​Rate Limiting

​Business Logic Errors

​Feature & Upgrade Errors

​File & Upload Errors

​Server Errors

​HTTP Status Code Summary

​Support Resources

System Status

Help Center

Discord Community

Contact Support

Error Codes Reference

Authentication & Authorization

Validation & Input Errors

Resource Errors

Rate Limiting

Business Logic Errors

Feature & Upgrade Errors

File & Upload Errors

Server Errors

HTTP Status Code Summary

Support Resources