On this page
No Headings
API error response for 422 Unprocessable Entity - business logic failures that prevent cart operations.
Use BusinessError (422) when:
Unlike technical errors (400/404/500), business errors can optionally include rich context about why the operation failed and what actions can resolve the issue, maintaining consistency with validation_issues patterns.
The business_context field is optional but only available on 422 responses. When present, it provides
the same ValidationIssue structure used in 200 responses, enabling consistent AI agent handling.
See ERROR_CODES.md for complete guidance on Error vs ValidationIssue vs BusinessError usage.
objectnamerequiredstringError name/type
messagerequiredstringError description
debug_idstringUnique error identifier for support
business_contextobjectOptional rich business context about why the cart operation failed. Only available on 422 Unprocessable Entity responses. Provides the same structure as validation_issues to maintain consistency across error handling patterns, enabling AI agents to understand and potentially resolve business constraint violations. When present, includes resolution options and actionable guidance.
coderequiredstring"INVENTORY_ISSUE", "PRICING_ERROR", "SHIPPING_ERROR", "PAYMENT_ERROR", "DATA_ERROR", "BUSINESS_RULE_ERROR"Consolidated error category
typerequiredstring"MISSING_FIELD", "INVALID_DATA", "BUSINESS_RULE"Type classification for error handling
messagerequiredstringTechnical message for developers and logging
user_messagestringCustomer-friendly message for end users
variant_idstringSpecific item ID if the issue is item-specific
fieldstringSpecific field name if the issue is field-specific
contextCategory-specific context information
anyOf[0]objectContext for inventory and stock-related issues
specific_issuestring"ITEM_OUT_OF_STOCK", "INSUFFICIENT_INVENTORY", "BACK_ORDERED", "PRE_ORDER_ONLY", "ITEM_DISCONTINUED", "LOW_STOCK_WARNING", "INVENTORY_RESERVED", "SEASONAL_UNAVAILABLE", "VARIANT_NOT_AVAILABLE", "CUSTOM_OPTION_UNAVAILABLE"Specific inventory issue type
item_idstringProduct item identifier
variant_idstringProduct variant identifier if applicable
available_quantityintegerCurrently available quantity
requested_quantityintegerRequested quantity
reserved_quantityintegerQuantity reserved for other transactions
restock_datestringdate-timeExpected restock date
estimated_ship_datestringdate-timeEstimated shipping date for back-orders
back_order_limitintegerMaximum allowed back-order quantity
current_back_ordersintegerCurrent number of back-orders
discontinuation_datestringdate-timeDate product was discontinued
suggested_alternativesarrayAlternative product IDs
itemsstringupgrade_availablebooleanWhether newer version is available
seasonal_start_datestringdate-timeWhen seasonal product becomes available
last_soldstringdate-timeWhen item was last sold
anyOf[1]objectContext for pricing and financial issues
specific_issuestring"PRICE_MISMATCH", "DISCOUNT_EXPIRED", "DISCOUNT_USAGE_LIMIT_EXCEEDED", "DISCOUNT_CUSTOMER_INELIGIBLE", "DISCOUNT_MINIMUM_NOT_MET", "TAX_CALCULATION_FAILED", "CURRENCY_NOT_SUPPORTED", "CURRENCY_MISMATCH", "PROMOTIONAL_CONFLICT"Specific pricing issue type
variant_idstringItem with pricing issue
original_pricestringOriginal price value
current_pricestringCurrent price value
currency_codestringCurrency code
price_change_reasonstring"promotional_ended", "promotional_started", "market_adjustment", "cost_increase", "seasonal_pricing", "component_cost_increase", "terms_updated"Reason for price change
price_increasestringAmount of price increase
price_decreasestringAmount of price decrease
coupon_codestringCoupon code with issues
usage_limitintegerCoupon usage limit
current_usageintegerCurrent coupon usage count
expiration_datestringdate-timeDiscount expiration date
minimum_order_amountstringMinimum order for discount
supported_currenciesarrayList of supported currencies
itemsstringfound_currenciesarrayMultiple currencies found in cart
itemsstringtax_service_errorstringTax calculation service error
current_datestringdate-timeCurrent system date for comparisons
discount_amountstringDiscount amount that was applied
required_currency_consistencybooleanWhether all items must use same currency
mixed_itemsarrayItems with different currencies
itemsobjectvariant_idstringcurrencystringanyOf[2]objectContext for shipping and address issues
specific_issuestring"MISSING_SHIPPING_ADDRESS", "SHIPPING_ADDRESS_INVALID", "SHIPPING_TO_PO_BOX_NOT_ALLOWED", "NO_SHIPPING_OPTIONS", "INTERNATIONAL_SHIPPING_RESTRICTED", "REGION_RESTRICTED", "OVERSIZED_ITEM_SHIPPING", "HAZARDOUS_MATERIAL_SHIPPING", "SHIPPING_ZONE_NOT_COVERED", "MISSING_COORDINATES_FOR_ENHANCED_DELIVERY"Specific shipping issue type
validation_failuresarraySpecific address validation failures
itemsstringsuggested_correctionsobjectSuggested address corrections
postal_codestringaddress_line_1stringadmin_area_2stringaddress_quality_scorenumberAddress validation quality score
restricted_itemsarrayItems with shipping restrictions
itemsstringrestriction_reasonstring"signature_required", "age_verification_required", "export_controlled", "hazardous_material", "oversized_item", "po_box_restriction"Reason for shipping restriction
po_box_detectedbooleanWhether PO Box was detected
destination_countrystringDestination country code
restricted_regionstringRestricted region identifier
supported_countriesarrayList of supported countries
itemsstringprovided_addressstringAddress string that failed validation
anyOf[3]objectContext for payment processing issues
specific_issuestring"PAYMENT_AMOUNT_TOO_LARGE", "PAYMENT_AMOUNT_TOO_SMALL", "PAYMENT_METHOD_NOT_ACCEPTED", "CURRENCY_CONVERSION_FAILED", "PAYMENT_PROCESSOR_UNAVAILABLE", "MERCHANT_ACCOUNT_ISSUE", "PAYMENT_DECLINED", "PAYMENT_INSUFFICIENT_FUNDS", "PAYMENT_EXPIRED", "PAYMENT_FRAUD_DETECTED"Specific payment issue type
order_totalstringTotal order amount
payment_limitstringMaximum payment limit
minimum_amountstringMinimum payment amount
excess_amountstringAmount exceeding limit
payment_methodstringPayment method being used
currency_codestringTransaction currency
from_currencystringSource currency for conversion
to_currencystringTarget currency for conversion
conversion_servicestringCurrency conversion service status
supported_payment_methodsarrayList of supported payment methods
itemsstringprocessor_error_codestringPayment processor specific error code
decline_reasonstringReason for payment decline
payment_tokenstringPayment token that was declined
anyOf[4]objectContext for data validation issues
specific_issuestring"MISSING_CHECKOUT_FIELDS", "MISSING_PAYMENT_METHOD", "MISSING_POLICY_ACCEPTANCE", "REQUIRED_FIELD_MISSING", "INVALID_EMAIL_FORMAT", "INVALID_PHONE_FORMAT", "FIELD_VALUE_TOO_LONG", "FIELD_VALUE_TOO_SHORT", "INVALID_DATE_FORMAT", "FUTURE_DATE_NOT_ALLOWED", "INVALID_CUSTOMER_DATA", "ITEM_NOT_FOUND", "INVALID_ITEM_DATA", "ITEM_ATTRIBUTE_MISMATCH"Specific data validation issue type
field_namestringName of the field with validation error
provided_valuestringValue that failed validation
expected_formatstringExpected format description
max_lengthintegerMaximum allowed length
min_lengthintegerMinimum required length
current_lengthintegerCurrent value length
regex_patternstringRequired regex pattern
suggested_valuestringSuggested corrected value
allowed_valuesarrayList of allowed values for enum fields
itemsstringrequired_fieldsarrayList of required field names
itemsstringfield_descriptionsobjectDescriptions for required fields
anyOf[5]objectContext for business logic violations
specific_issuestring"MINIMUM_ORDER_NOT_MET", "MINIMUM_QUANTITY_NOT_MET", "MAXIMUM_QUANTITY_EXCEEDED", "CART_LIMIT_EXCEEDED", "CUSTOMER_ACCOUNT_SUSPENDED", "PURCHASE_LIMIT_EXCEEDED", "BULK_ORDER_APPROVAL_REQUIRED", "STORE_TEMPORARILY_CLOSED", "AGE_RESTRICTED_PRODUCT", "LOYALTY_PROGRAM_VALIDATION_FAILED", "BUSINESS_HOURS_RESTRICTION", "PRODUCT_ARCHIVED"Specific business rule issue type
current_amountstringCurrent order amount
required_amountstringRequired minimum amount
maximum_amountstringMaximum allowed amount
remaining_amountstringAmount needed to meet minimum
account_statusstringCustomer account status
suspension_reasonstringReason for account suspension
suspension_datestringdate-timeDate of account suspension
monthly_limitstringMonthly purchase limit
current_month_totalstringCurrent month purchase total
reset_datestringdate-timeWhen limits reset
total_quantityintegerTotal quantity in bulk order
approval_thresholdintegerQuantity requiring approval
maintenance_end_timestringdate-timeWhen maintenance ends
service_statusstringCurrent service status
retry_afterintegerSeconds before retry recommended
contact_infostringSupport contact information
restricted_itemsarrayItems with restrictions
itemsstringage_requirementintegerRequired minimum age
business_hoursobjectStore business hours
open_timestringclose_timestringtimezonestringshortage_amountstringAmount needed to meet minimum requirements
exceeds_bystringAmount by which limit is exceeded
resolution_optionsarrayAvailable actions to resolve this issue
itemsobjectAvailable action to resolve a validation issue
actionrequiredstring"REDIRECT_TO_MERCHANT", "MODIFY_CART", "ACCEPT_NEW_PRICE", "ACCEPT_BACK_ORDER", "SUGGEST_ALTERNATIVE", "REMOVE_ITEM", "UPDATE_ADDRESS", "PROVIDE_MISSING_FIELD", "USE_DIFFERENT_PAYMENT", "SPLIT_ORDER", "CONTACT_SUPPORT", "RETRY_LATER", "REQUEST_APPROVAL", "WAIT_FOR_RESTOCK", "USE_DIFFERENT_CURRENCY", "ACCEPT_PRE_ORDER", "UPDATE_SHIPPING_METHOD", "ACCEPT_TERMS", "VERIFY_ACCOUNT", "APPLY_DIFFERENT_COUPON", "REMOVE_COUPON", "CHOOSE_DIFFERENT_VARIANT"Machine-readable action identifier
labelrequiredstringHuman-readable action label
urlstringuriURL to redirect to for resolution
metadataobjectAdditional action metadata
cost_impactstringFinancial impact of this action
prioritystring"HIGH", "MEDIUM", "LOW"Priority level for this resolution
auto_applicablebooleanWhether this action can be applied automatically
estimated_timestringEstimated time for resolution
redirect_requiredbooleanWhether this action requires user redirect
detailsarrayAdditional technical details if needed
itemsobjectfieldstringissuestringdescriptionstring