Skip to main content
The Komerza API uses standard HTTP status codes along with specific error codes to indicate the type of error that occurred. Error responses include a machine-readable error code and a human-readable message.

​
Error Response Format

All error responses follow this structure: 
{
  "success": false,
  "message": "The request contains invalid parameters",
  "code": "ValidationError",
  "data": null
}

​
Success Response Format

For comparison, successful responses look like this: 
{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example Product"
  }
}

​
Paginated Response Format

Paginated endpoints return data in this format: 
{
  "success": true,
  "pages": 5,
  "data": [
    { "id": "1", "name": "Item 1" },
    { "id": "2", "name": "Item 2" }
  ]
}

​
Error Codes Reference

​
Authentication & Authorization

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
}
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
}
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
}
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

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
}
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

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
}
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

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

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
}
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
}
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

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
}
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
}
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

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

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 CodeError CodesDescription
400ValidationError, BadCaptcha, ProductUnavailable, NotEnoughFunds, UnsupportedRequest, UploadFailedBad Request - Invalid input
401BadToken, OAuthLoginRequiredUnauthorized - Invalid or missing authentication
402UpgradeRequiredPayment Required - Plan upgrade needed
403AccessDenied, TwoFactorRequired, VerificationRequired, FeatureUnavailableForbidden - Insufficient permissions
404NotFoundNot Found - Resource doesn’t exist
409ObjectConflictConflict - Resource conflict
429RateLimitedToo Many Requests - Rate limit exceeded
500InternalServerErrorInternal 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