📍 Bolt Help / APIs, SDKs, & Webhooks / Error Codes

Error Codes

Learn about error codes for orders, discounts, shipping details, and tax calculations.

Page Contents

You may choose to pass these error codes back to Bolt in Merchant Callback API Responses to trigger appropriate messages for the shopper.

Application Error Codes

Code #	Code	Text Prompt
4001	AppMerchantSettingsCreate	Failed to create merchant settings.
4002	AppMerchantSettingsLoad	Failed to load merchant settings.
4003	AppMerchantKeyCreate	N/A
4004	AppMerchantKeyLoad	Unable to find the entity by key. Please check the key in the request.
4005	AppInvalidJSON	Invalid JSON content.
4006	AppUnknownContentType	N/A
4007	AppFileUpload	Failed to upload the file. Please check the file contents and retry.
4008	AppNonceInvalid	The provided nonce value is invalid. Please check the value and retry.
4009	AppNonceExpired	The provided nonce value expired. Please retry the request by regenerating a new nonce.
4010	AppMerchantKeyUpdate	N/A
4011	AppFileInvalidName	Invalid filename provided.
4012	AppNotRightNow	N/A

Common API Error Codes

Code #	Definition
400	Bad request.
401	Unauthorized user.
403	Forbidden by the server.
404	Resource not found.
409	Concurrent idempotent requests.
429	User sent too many requests and was rate limited by the server.
500	Internal server error.
502	Bad gateway.
503	Server was not ready to handle the request.
504	Gateway cannot get a response and timed out.

Authentication Error Codes

Code #	Code	Text Prompt
1001	AuthGuestSessionRequired	Authentication error. A guest session is required.
1002	AuthInvalidSessionType	Authentication error. The provided session type has no access to this resource.
1003	AuthInvalidSessionLevel	Authentication error. The provided session level has no access to this resource.
1004	AuthInvalidUserRole	Authentication error. Invalid user role.
1005	AuthInvalidMerchantKey	Authentication error. Invalid merchant key.
1006	AuthMerchantNotFound	Authentication error. Merchant not found.
1007	AuthInvalidNonce	Authentication error. Invalid nonce value.
1009	AuthInvalidSessionToken	Authentication error. Invalid session token.
1010	AuthUserNotFound	Authentication error. User not found.
1011	AuthMerchantKeyMerchantMismatch	Authentication error. Merchant key doesn’t match merchant public id.
1012	AuthMerchantKeyDivisionMismatch	Authentication error. Merchant key doesn’t match division public id.
1013	AuthUpdateExpirationFailed	N/A
1014	AuthInvalidTwilioSignature	Authentication error. Invalid twilio signature
1015	AuthUnauthorized	Authentication error. Authorization required.

Basic (General) Error Codes

Code #	Code	Text Prompt
1	EmptyValue	A required field is empty.
2	InvalidAmount	A valid amount is required.
3	InvalidAutocapture	Transaction must match the configured autocapture setting.
4	InvalidCountry	A valid country name or country code must be provided.
5	InvalidCreditCardNumber	A valid credit card number must be provided.
6	InvalidCurrency	A valid currency code must be provided.
7	InvalidEmail	A valid email address must be provided.
8	InvalidFormat	Invalid field format.
9	InvalidLength	Invalid field length.
10	InvalidNumber	A valid number must be provided.
11	InvalidPassword	The provided password doesn’t match the required format.
12	InvalidPhone	A valid phone number must be provided.
13	InvalidPostalCode	A valid postal code must be provided.
14	InvalidURL	A valid URL string must be provided.
15	InvalidValue	A valid value must be provided.
16	NewLine	Unexpected new line character in input.
17	InvalidDate	A valid date value must be provided.
18	Forbidden	This action is forbidden.
21	AmountTooLow	The provided amount is lower than required.
22	AmountTooHigh	The provided amount is higher than required.
24	NotFound	The requested entity was not found.
25	MissingInputParameter	The input is missing a required parameter.
26	InvalidInputParameter	A parameter provided in the input is invalid.
27	InvalidSignature	Invalid signature.
28	ExpiredEntity	The entity has expired.
29	InactiveEntity	The entity is not active.
30	Unsupported	This feature is not supported.
31	ShippingCostTooHigh	The shipping cost is too high.
32	CodeAlreadyUsed	The code is already used.
33	NoApplicableItem	No applicable item found in the request.
34	AlreadyExists	The entity already exists.
35	RateLimited	Rate limit reached. Please retry after a while.
36	UserNotEligible	The user is not eligible for this action.
37	InvalidImageFormat	The format of the image is not valid
38	CantChangeRoleOfPrimaryUser	N/A
39	NonMerchantRole	N/A
40	InvalidRole	N/A
41	TooManyRequests	Too many requests
42	NonRetryableError	N/A
43	NoPoBoxAllowed	Shipment to PO Box is not allowed.
44	InvalidAddress	A valid address address must be provided.
45	TransactionNotAuthorized	Transaction is not in authorized state. Transaction may not have been approved.
46	InternalServerError	Internal error
47	BadGateway	N/A
48	NoShippingOptionAvailable	N/A
49	InvalidTokenType	N/A
50	BadRequest	N/A
51	BadResponse	N/A
19 - Deprecated	ErrorWeakPassword	N/A
20 - Deprecated	ServiceError	N/A
23 - Deprecated	ErrorMutuallyExclusive	N/A

Create Order Error Codes

Respond with specific errors for order.create.

Code	Code Name	Text Prompt
2001003	CartHasExpired	Your session timed out due to inactivity. Please refresh your cart and try again.
2001004	ItemPriceHasBeenUpdated	Item details were out-of-date and have been updated, please try again.
2001005	OutOfInventory	An item in your cart is no longer available. Please refresh your cart and try again.
2001006	DiscountCannotApply	One or more items in the cart are not eligible for discount. Please refresh and try again.
2001008	ShippingPriceHasBeenUpdated	The shipping amount for your cart has changed. Please refresh your cart and try again.

Custom Checkbox Error Codes

Code #	Code	Text Prompt
4013	CustomCheckboxLimitReached	Merchant division cannot have more than 3 active Checkboxes.
4014	CustomCheckboxLookupFailed	Failed to fetch checkboxes for merchant division.
4015	CustomCheckboxAlreadyExists	Checkbox with supplied ID already exists.

Discount Error Codes

Respond with specific errors for discount.code.apply.

Code	Code Name	Text Prompt
6200	DiscountCodeInsufficientInformation	We need more information to apply the discount. Please continue to checkout.
6201	DiscountCodeInvalid	Discount code invalid. Please refresh and try again.
6202	DiscountCodeExpired	Discount code expired. Please refresh and try again.
6203	DiscountCodeNotAvailable	The discount code is not available.
6204	DiscountCodeLimitReached	The discount code has exceeded usage limit.
6205	DiscountCodeMinCartAmountRequired	The total cart amount is too low for this discount.
6206	DiscountCodeUniqueEmailRequired	The email address has already redeemed the discount.
6207	DiscountCodeItemsNotEligible	One or more items in the cart are not eligible for discount. Please refresh and try again.
6208	DiscountCodeItemQuantityTooLow	The cart does not have enough items to meet the discount requirement.

ErrorApplicationBase Error Codes

Code #	Code	Text Prompt
1000000	ErrorAuthentication	N/A
1000001	ErrorInvalidId	N/A
1000002	ErrorInvalidIdentifier	N/A
1000003	ErrorProcessing	N/A
1000004	ErrorNotFound	N/A
1000005	ErrorInvalidState	N/A
1000006	ErrorPagination	N/A
1000007	ErrorMissingAuthenticationFactor	N/A
1000008	ErrorLockedOut	N/A
1000009	ErrorDeclined	N/A
1000010	ErrorInvalidReference	N/A
1000011	ErrorDeclinedInvalidAmount	N/A
1000012	ErrorDeclinedInvalidCvv	N/A
1000013	ErrorDeclinedInvalidNumber	N/A
1000014	ErrorDeclinedExpired	N/A
1000015	ErrorDeclinedCallIssuer	N/A
1000016	ErrorDeclinedInvalidMerchantForCard	N/A
1000017	ErrorInvalidWebhookType	N/A
1000018	ErrorDuplicateCreditCardTransaction	N/A
1000019	ErrorTransactionHasDisputes	N/A
1000020	ErrorRefundDeclined	N/A

Merchant Cart Error Codes

Code	Code Name	Text Prompt
6300	MerchantCartUnknownError	An unknown error occurred when fetching the cart.
6301	MerchantCartOutOfStock	An item in your cart is no longer available. Please refresh your cart and try again.
6302	MerchantCartInvalidSize	The sizes for some of the items are invalid.
6303	MerchantCartInvalidQuantity	The quantities for some of the items are invalid.
6304	MerchantCartInvalidReference	The references for some of the items are invalid.
6305	MerchantCartInvalidAmount	An item in your cart has been updated. Please refresh your cart and try again.
6306	MerchantCartExpired	Your session timed out due to inactivity. Please refresh your cart and try again.
6307	MerchantOrderAlreadyExists	Your order may have been placed. Please check your email for an order confirmation. If you did not receive an email please refresh this page and retry checkout.

Shipping and Tax Error Codes

Respond with specific errors for order.shipping_and_tax.

Code	Code Name	Text Prompt
6100	IntegrationInvalidAddress	Delivery is not available for this order.
6101	IntegrationNoPoBoxAllowed	Address with P.O. Box is not allowed.
6103	IntegrationCustomShippingTaxError	custom error message

# bolt-api # merchant-api # troubleshooting # webhooks

Tokenizer API Reference

OAuth at Bolt