---
title: 'shopify:cart:error'
description: Fires when a cart operation fails.
source_url:
  html: 'https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-error'
  md: >-
    https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-error.md
api_name: storefront-events-and-actions
---

# shopify:cart:error

Fires when a cart operation fails, such as an add to cart that the cart rejects.

You can use this to tell a failure from an operation that's still running, so an optimistic update rolls back rather than staying on screen.

You dispatch it from the same element as the operation that failed. Without an [`eventTarget`](https://shopify.dev/docs/api/storefront-events-and-actions/actions/configure#eventtarget), an action dispatches it from `document`.

This event reaches every listener, which is how an app learns about a failure it didn't cause. It fires only when the request itself failed, and the promise of that operation rejects at the same time. A cart that declines a change isn't a failure: the promise [resolves](https://shopify.dev/docs/api/storefront-events-and-actions/events/listen#waiting-for-the-result) with `userErrors` and no error event.

#### Properties

* **error**

  **string**

  **required**

  A human-readable message describing what failed. Don't parse this. Branch on `code` instead.

* **code**

  **CartErrorCode**

  **required**

  The reason the operation failed. Branch on this rather than on `error`.

* **detail**

  **Record\<string, unknown>**

  Optional custom data for the storefront's internal use. Listeners can read it.

### CartErrorCode

The reason a cart operation failed. These values match the Storefront API \[\`CartErrorCode\`]\(/docs/api/storefront/latest/enums/CartErrorCode) enum.

```ts
'ADDRESS_FIELD_CONTAINS_EMOJIS' | 'ADDRESS_FIELD_CONTAINS_HTML_TAGS' | 'ADDRESS_FIELD_CONTAINS_URL' | 'ADDRESS_FIELD_DOES_NOT_MATCH_EXPECTED_PATTERN' | 'ADDRESS_FIELD_IS_REQUIRED' | 'ADDRESS_FIELD_IS_TOO_LONG' | 'BUNDLES_AND_ADDONS_CANNOT_BE_MIXED' | 'BUYER_CANNOT_PURCHASE_FOR_COMPANY_LOCATION' | 'CART_TOO_LARGE' | 'GIFT_CARD_RECIPIENT_INVALID' | 'INVALID' | 'INVALID_COMPANY_LOCATION' | 'INVALID_DELIVERY_ADDRESS_ID' | 'INVALID_DELIVERY_GROUP' | 'INVALID_DELIVERY_OPTION' | 'INVALID_INCREMENT' | 'INVALID_MERCHANDISE_LINE' | 'INVALID_METAFIELDS' | 'INVALID_ZIP_CODE_FOR_COUNTRY' | 'INVALID_ZIP_CODE_FOR_PROVINCE' | 'LESS_THAN' | 'MAXIMUM_EXCEEDED' | 'MERCHANDISE_NOT_APPLICABLE' | 'MINIMUM_NOT_MET' | 'MISSING_CUSTOMER_ACCESS_TOKEN' | 'MISSING_DISCOUNT_CODE' | 'MISSING_NOTE' | 'NOTE_TOO_LONG' | 'ONLY_ONE_DELIVERY_ADDRESS_CAN_BE_SELECTED' | 'PARENT_LINE_INVALID_REFERENCE' | 'PARENT_LINE_NESTING_TOO_DEEP' | 'PARENT_LINE_NOT_FOUND' | 'PARENT_LINE_OPERATION_BLOCKED' | 'PENDING_DELIVERY_GROUPS' | 'PROVINCE_NOT_FOUND' | 'SELLING_PLAN_NOT_APPLICABLE' | 'SERVICE_UNAVAILABLE' | 'TOO_MANY_DELIVERY_ADDRESSES' | 'UNSPECIFIED_ADDRESS_ERROR' | 'VALIDATION_CUSTOM' | 'VARIANT_REQUIRES_SELLING_PLAN' | 'ZIP_CODE_NOT_SUPPORTED'
```

Examples

### Examples

* ####

  ##### Dispatch the event

  ```javascript
  import { CartErrorEvent } from '@shopify/standard-events';

  element.dispatchEvent(
    new CartErrorEvent({
      error: 'Only 3 left in stock.',
      code: 'MAXIMUM_EXCEEDED',
    }),
  );
  ```

* ####

  ##### Listen for the event

  ```javascript
  document.addEventListener('shopify:cart:error', (event) => {
    if (event.code === 'MAXIMUM_EXCEEDED') {
      showMessage(event.error);
      return;
    }

    showMessage('Something went wrong. Try again.');
  });
  ```

***