This comprehensive reference covers all error codes returned by the APIs. Each error includes a description, common causes, and resolution steps.
Error Response Format
All API errors follow a consistent JSON structure:{
"code": 400,
"error": "InvalidToken",
"description": "Jwt token is invalid."
}
code(number): HTTP status codeerror(string): Error identifier/typedescription(string): Human-readable error description
Error Categories
- Authentication
- Cart Operations
- Product & Inventory
- Shipment & Fulfillment
- Checkout & Address
- Promotions
- Addons
- Validation
- System
Authentication Errors
ErrorUnauthorized
ErrorUnauthorized
HTTP Status: 401Description: Invalid or missing authentication tokenCommon Causes:
- Missing
x-firmly-authorizationheader - Expired authentication token
- Invalid token format
- Ensure the authorization header is included
- Check token expiration and refresh if needed
- Verify token format matches expected pattern
// Correct header format
headers: {
'x-firmly-authorization': 'Bearer your-token-here'
}
MissingAuthHeader
MissingAuthHeader
HTTP Status: 401Description: Authorization header not providedCommon Causes:
- Header name typo
- Header not included in request
- Add the
x-firmly-authorizationheader - Check for typos in header name
ErrorInvalidSession
ErrorInvalidSession
HTTP Status: 401Description: Session has expired or is invalidCommon Causes:
- Session timeout
- Session transferred to another device
- Invalid session ID
- Create a new session
- Re-authenticate the user
Cart Operation Errors
ErrorCartNotFound
ErrorCartNotFound
HTTP Status: 404Description: Cart does not exist for the specified domainCommon Causes:
- Cart ID doesn’t exist
- Wrong domain specified
- Cart has expired
- Verify the cart ID and domain
- Create a new cart if needed
- Check cart expiration settings
ErrorNoLineItem
ErrorNoLineItem
HTTP Status: 400Description: Cart is empty or has no line itemsCommon Causes:
- Attempting operations on empty cart
- All items have been removed
- Cart cleared but not populated
- Add items to cart before proceeding
- Check if items were accidentally cleared
- Validate cart state before operations
ErrorLineItemNotFound
ErrorLineItemNotFound
HTTP Status: 404Description: Specified line item not found in cartCommon Causes:
- Invalid line item ID
- Item already removed
- Wrong cart context
- Refresh cart to get current line item IDs
- Verify line item exists before updating
- Use correct line item ID from cart response
ErrorInvalidQuantity
ErrorInvalidQuantity
HTTP Status: 400Description: Invalid quantity specifiedCommon Causes:
- Negative quantity
- Zero quantity (use remove instead)
- Exceeds maximum allowed
- Use positive integers for quantity
- Set quantity to 0 to remove item
- Check merchant quantity limits
Product and Inventory Errors
ErrorProductNotFound
ErrorProductNotFound
HTTP Status: 404Description: Product or variant not foundCommon Causes:
- Invalid variant ID
- Product no longer available
- Wrong product/variant reference
- Verify variant ID is correct
- Check if product is still active
- Use product search to find correct ID
ErrorProductNotSupported
ErrorProductNotSupported
HTTP Status: 400Description: Product cannot be added to cartCommon Causes:
- Product type restrictions
- Regional availability
- Business rules preventing addition
- Check product eligibility rules
- Verify customer location
- Contact support for restrictions
ErrorNotEnoughStock
ErrorNotEnoughStock
HTTP Status: 400Description: Insufficient inventory availableCommon Causes:
- Requested quantity exceeds stock
- Stock depleted during checkout
- Reserved inventory limits
- Reduce quantity to available stock
- Check real-time inventory levels
- Enable back-order if supported
Shipment and Fulfillment Errors
ErrorShipmentNotFound
ErrorShipmentNotFound
HTTP Status: 404Description: Specified shipment not foundCommon Causes:
- Invalid shipment ID
- Shipment removed or consolidated
- Wrong cart context
- Get current cart to refresh shipment IDs
- Verify shipment ID before operations
- Check if shipments were reorganized
{
"code": 404,
"error": "ErrorShipmentNotFound",
"description": "Shipment not found"
}
ErrorInvalidFulfillmentType
ErrorInvalidFulfillmentType
HTTP Status: 400Description: Invalid or unsupported fulfillment typeCommon Causes:
- Type not available for items
- Invalid enum value
- Merchant doesn’t support type
- Check available fulfillment types
- Use valid enum values only
- Verify merchant configuration
ErrorShippingNotNeeded
ErrorShippingNotNeeded
HTTP Status: 400Description: Shipping not required for cartCommon Causes:
- Digital-only products
- All items use pickup
- No physical items in cart
- Skip shipping configuration
- Check product types
- Proceed to billing only
Checkout and Address Errors
ErrorCountryNotSupported
ErrorCountryNotSupported
HTTP Status: 400Description: Country not supported by merchantCommon Causes:
- Shipping restrictions
- Invalid country code
- Regional limitations
- Use supported country codes
- Check merchant shipping zones
- Verify country format (ISO 3166)
ErrorInvalidState
ErrorInvalidState
HTTP Status: 400Description: Invalid state/province codeCommon Causes:
- Wrong state code format
- State doesn’t match country
- Invalid abbreviation
- Use standard state codes
- Match state to selected country
- Use full state name if needed
ErrorInvalidEmail
ErrorInvalidEmail
HTTP Status: 400Description: Invalid email formatCommon Causes:
- Malformed email address
- Missing @ symbol
- Invalid domain
- Validate email format
- Check for typos
- Use standard email validation
ErrorInvalidShippingInfo
ErrorInvalidShippingInfo
HTTP Status: 400Description: Shipping information validation failedCommon Causes:
- Missing required fields
- Invalid postal code
- Address validation failure
- Provide all required fields
- Verify address format
- Check postal code validity
Promotion and Discount Errors
ErrorInvalidPromoCode
ErrorInvalidPromoCode
HTTP Status: 400Description: Promotional code is invalid or expiredCommon Causes:
- Code doesn’t exist
- Code has expired
- Already used (single-use codes)
- Verify code spelling
- Check expiration date
- Try alternative codes
ErrorPromoNotAvailable
ErrorPromoNotAvailable
HTTP Status: 400Description: Promo code not applicable to cartCommon Causes:
- Minimum purchase not met
- Excluded products in cart
- Customer not eligible
- Check promotion requirements
- Verify cart meets conditions
- Remove excluded items
ErrorClearPromoCodeNotAllowed
ErrorClearPromoCodeNotAllowed
HTTP Status: 403Description: Merchant disabled promo code clearingCommon Causes:
- Business rule restriction
- Promotional lock
- Contact merchant support
- Create new cart if needed
Addon Service Errors
ErrorAddonNotFound
ErrorAddonNotFound
HTTP Status: 404Description: Addon not found or not availableCommon Causes:
- Invalid addon ID
- Addon no longer offered
- Not eligible for cart items
- Get available addons from cart
- Verify addon ID is current
- Check addon eligibility rules
ErrorAddonNotApplicable
ErrorAddonNotApplicable
HTTP Status: 400Description: Addon cannot be applied to selected itemsCommon Causes:
- Wrong item selection
- Incompatible product types
- Exceeded addon limits
- Check addon scope rules
- Verify item compatibility
- Review addon constraints
ErrorAddonConflict
ErrorAddonConflict
HTTP Status: 400Description: Addon conflicts with existing selectionsCommon Causes:
- Exclusive addon groups
- Duplicate addon application
- Constraint violations
- Remove conflicting addons
- Check exclusive groups
- Review addon rules
Input Validation Errors
ErrorBadRequest
ErrorBadRequest
HTTP Status: 400Description: General bad request errorCommon Causes:
- Malformed JSON
- Missing required parameters
- Invalid data types
- Validate JSON syntax
- Check API documentation
- Ensure proper data types
ErrorInvalidInputBody
ErrorInvalidInputBody
HTTP Status: 400Description: Request body validation failedCommon Causes:
- Schema validation failure
- Missing required fields
- Invalid field values
- Review request schema
- Include all required fields
- Validate field formats
ErrorUnprocessableEntity
ErrorUnprocessableEntity
HTTP Status: 422Description: Request understood but cannot be processedCommon Causes:
- Business logic violations
- Invalid state transitions
- Constraint failures
- Check business rules
- Verify operation sequence
- Review error details
System and Service Errors
ErrorStoreUnavailable
ErrorStoreUnavailable
HTTP Status: 503Description: Store service temporarily unavailableCommon Causes:
- Service maintenance
- Temporary outage
- Rate limiting
- Retry with exponential backoff
- Check service status
- Contact support if persistent
ErrorInternalServer
ErrorInternalServer
HTTP Status: 500Description: Internal server error occurredCommon Causes:
- Unexpected server issue
- Database connectivity
- Service dependencies
- Retry the request
- Report to support with request ID
- Check service status page
ErrorTimeout
ErrorTimeout
HTTP Status: 504Description: Request timed outCommon Causes:
- Long-running operation
- Network issues
- Server overload
- Retry with smaller payload
- Check network connectivity
- Use pagination if available
Quick Reference Table
| Error Code | HTTP Status | Category | Quick Fix |
|---|---|---|---|
ErrorUnauthorized | 401 | Auth | Check auth token |
ErrorCartNotFound | 404 | Cart | Verify cart ID |
ErrorProductNotFound | 404 | Product | Check variant ID |
ErrorNotEnoughStock | 400 | Inventory | Reduce quantity |
ErrorInvalidPromoCode | 400 | Promo | Verify code |
ErrorCountryNotSupported | 400 | Checkout | Use valid country |
ErrorShipmentNotFound | 404 | Shipment | Refresh cart |
ErrorAddonNotFound | 404 | Addon | Check addon ID |
ErrorInvalidInputBody | 400 | Validation | Fix request body |
ErrorStoreUnavailable | 503 | System | Retry request |
Need Help?
If you encounter persistent errors or need assistance:API Status
Check current service status
Support
Contact our support team