This comprehensive reference covers all error codes returned by the APIs. Each error includes a description, common causes, and resolution steps.
{
"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
HTTP Status: 401Description: Invalid or missing authentication tokenCommon Causes:
- Missing
x-firmly-authorization header
- Expired authentication token
- Invalid token format
Resolution:
- 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'
}
HTTP Status: 401Description: Session has expired or is invalidCommon Causes:
- Session timeout
- Session transferred to another device
- Invalid session ID
Resolution:
- Create a new session
- Re-authenticate the user
Cart Operation Errors
HTTP Status: 404Description: Cart does not exist for the specified domainCommon Causes:
- Cart ID doesn’t exist
- Wrong domain specified
- Cart has expired
Resolution:
- Verify the cart ID and domain
- Create a new cart if needed
- Check cart expiration settings
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
Resolution:
- Add items to cart before proceeding
- Check if items were accidentally cleared
- Validate cart state before operations
HTTP Status: 404Description: Specified line item not found in cartCommon Causes:
- Invalid line item ID
- Item already removed
- Wrong cart context
Resolution:
- Refresh cart to get current line item IDs
- Verify line item exists before updating
- Use correct line item ID from cart response
HTTP Status: 400Description: Invalid quantity specifiedCommon Causes:
- Negative quantity
- Zero quantity (use remove instead)
- Exceeds maximum allowed
Resolution:
- Use positive integers for quantity
- Set quantity to 0 to remove item
- Check merchant quantity limits
Product and Inventory Errors
HTTP Status: 404Description: Product or variant not foundCommon Causes:
- Invalid variant ID
- Product no longer available
- Wrong product/variant reference
Resolution:
- Verify variant ID is correct
- Check if product is still active
- Use product search to find correct ID
HTTP Status: 400Description: Product cannot be added to cartCommon Causes:
- Product type restrictions
- Regional availability
- Business rules preventing addition
Resolution:
- Check product eligibility rules
- Verify customer location
- Contact support for restrictions
HTTP Status: 400Description: Insufficient inventory availableCommon Causes:
- Requested quantity exceeds stock
- Stock depleted during checkout
- Reserved inventory limits
Resolution:
- Reduce quantity to available stock
- Check real-time inventory levels
- Enable back-order if supported
Shipment and Fulfillment Errors
HTTP Status: 404Description: Specified shipment not foundCommon Causes:
- Invalid shipment ID
- Shipment removed or consolidated
- Wrong cart context
Resolution:
- 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
HTTP Status: 400Description: Invalid or unsupported fulfillment typeCommon Causes:
- Type not available for items
- Invalid enum value
- Merchant doesn’t support type
Resolution:
- Check available fulfillment types
- Use valid enum values only
- Verify merchant configuration
HTTP Status: 400Description: Shipping not required for cartCommon Causes:
- Digital-only products
- All items use pickup
- No physical items in cart
Resolution:
- Skip shipping configuration
- Check product types
- Proceed to billing only
Checkout and Address Errors
HTTP Status: 400Description: Country not supported by merchantCommon Causes:
- Shipping restrictions
- Invalid country code
- Regional limitations
Resolution:
- Use supported country codes
- Check merchant shipping zones
- Verify country format (ISO 3166)
HTTP Status: 400Description: Invalid state/province codeCommon Causes:
- Wrong state code format
- State doesn’t match country
- Invalid abbreviation
Resolution:
- Use standard state codes
- Match state to selected country
- Use full state name if needed
HTTP Status: 400Description: Invalid email formatCommon Causes:
- Malformed email address
- Missing @ symbol
- Invalid domain
Resolution:
- Validate email format
- Check for typos
- Use standard email validation
HTTP Status: 400Description: Shipping information validation failedCommon Causes:
- Missing required fields
- Invalid postal code
- Address validation failure
Resolution:
- Provide all required fields
- Verify address format
- Check postal code validity
ErrorClearPromoCodeNotAllowed
Addon Service Errors
HTTP Status: 404Description: Addon not found or not availableCommon Causes:
- Invalid addon ID
- Addon no longer offered
- Not eligible for cart items
Resolution:
- Get available addons from cart
- Verify addon ID is current
- Check addon eligibility rules
HTTP Status: 400Description: Addon cannot be applied to selected itemsCommon Causes:
- Wrong item selection
- Incompatible product types
- Exceeded addon limits
Resolution:
- Check addon scope rules
- Verify item compatibility
- Review addon constraints
HTTP Status: 400Description: Addon conflicts with existing selectionsCommon Causes:
- Exclusive addon groups
- Duplicate addon application
- Constraint violations
Resolution:
- Remove conflicting addons
- Check exclusive groups
- Review addon rules
HTTP Status: 400Description: General bad request errorCommon Causes:
- Malformed JSON
- Missing required parameters
- Invalid data types
Resolution:
- Validate JSON syntax
- Check API documentation
- Ensure proper data types
HTTP Status: 400Description: Request body validation failedCommon Causes:
- Schema validation failure
- Missing required fields
- Invalid field values
Resolution:
- Review request schema
- Include all required fields
- Validate field formats
HTTP Status: 422Description: Request understood but cannot be processedCommon Causes:
- Business logic violations
- Invalid state transitions
- Constraint failures
Resolution:
- Check business rules
- Verify operation sequence
- Review error details
System and Service Errors
HTTP Status: 503Description: Store service temporarily unavailableCommon Causes:
- Service maintenance
- Temporary outage
- Rate limiting
Resolution:
- Retry with exponential backoff
- Check service status
- Contact support if persistent
HTTP Status: 500Description: Internal server error occurredCommon Causes:
- Unexpected server issue
- Database connectivity
- Service dependencies
Resolution:
- Retry the request
- Report to support with request ID
- Check service status page
HTTP Status: 504Description: Request timed outCommon Causes:
- Long-running operation
- Network issues
- Server overload
Resolution:
- 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:
