Listings Items API Issues Troubleshooting

Context and troubleshooting for common issues during Listings Items integration.

Listings Items API issue troubleshooting

The Listings Items API provides programmatic access to selling partner listings on Amazon. You can create, edit, delete, and retrieve details about Amazon listings (SKUs) for a selling partner. This includes product facts, such as item titles, and sales terms, such as price and inventory.

Listings data submitted to the Listings Items API abide by the JSON Schema format provided by the Selling Partner API for Product Type Definitions.

The following troubleshooting tips can help unblock you if you encounter issues reported for a listing either on submission, during the process, or independent of the submission process in general.

How are Listings Issues received?

Synchronous vs Asynchronous

Within the listing experience, you can access issues during different parts of the process. You can receive issues synchronously when submitting to the Listings API that prevent acceptance and further processing of the submission. You can also receive asynchronous notifications for issues reported after the submission was made. Issues can also be retrieved when reading listings data.

A synchronous issue occurs when the server rejects the request during the initial request. This most likely is an issue related to incorrect attributes or mishandled parameters attached to the request.

An asynchronous issue occurs when a request passes the initial validation but returns an error after processing the data received. The issue returned is in the form of a message that can be used to resolve the problem.

Post submission processing

Amazon performs a number of validations on submissions made by selling partners. Some of these validations are returned synchronously in response to the submissions. These cover data validations on the input itself, such as missing required attributes and invalid attributes.

If the submission passes the preceding synchronous validations, the submission is accepted and is sent downstream to create or update the SKU. There are a number of downstream processes that are then performed to successfully create an item in the Amazon catalog. Any of these downstream processes can generate issues which are returned asynchronously.

To adequately handle all possible issues, a client must handle issues reported both synchronously and asynchronously.

Issue codes and messages - what they mean and how to avoid them

Issue Code	Listing Issues	Description	Additional Details and Preventative Actions
90220	`attribute_name` is required but not supplied.	This issue occurs when a required attribute was not provided. Example: `item_package_dimensions` is required but not supplied. Provide information for the required attribute as indicated in the issue message.	To avoid this, use the Product Type Definitions API to identify required attributes and add to validation checks. Use the Notifications API to be updated with instant updates of Product Type definitions.
4000001	The provided value for `attribute_name` is invalid.	The value provided for the specified attribute is invalid. Certain attributes have restricted lists of permissible values. This issue is most commonly associated with Product Category, Product Subcategory, Item Type Keyword, or Recommended Browse Node. Note that conditionality must be followed, meaning that only certain subcategories can be selected for a certain product category and only certain browse nodes for certain subcategories.	To avoid this, use the Product Type Definitions API to verify permitted values and conditionality and ensure that they reflect the list of accepted values that can be selected within your system.
4005011	The value of `attribute_name` conflicts with another item in the Amazon catalogue, `conflicting_asin`. Either change the value to `conflicting_value` or contact Amazon to resolve the conflicting data issue.	This issue is returned when the submission has data that conflicts with another item in the Amazon catalog. You should review the conflicting information for the referenced ASIN and attribute. You might need to change the data being submitted to resolve the conflict with the existing data. If you wish to change any existing values, you will need to submit an Amazon Support case.	Build a workflow to surface any pre-existing catalog data for the SKU using the `getListingsItem` and `getCatalogItem` API.
99022	The field `field_name` for the attribute `attribute_name` does not have enough values. The required minimum is `min_occurrences` value(s).	Minimum value not met. This issue is generated when the value submitted for a field does not meet the minimum requirements or is missing. Review the issue message to identify the missing values/requirements and ask the vendor to resubmit. Example: Expected at least `1` of field `currency` for attribute `list_price`. When adding a list price you are required to provide a value for currency (e.g GB, EUR).	A recommended solution to avoid this is adding validation checks within your system to highlight where minimum requirements have not been met.
4005034	Increasing cost value is not supported. Use the Edit Item Costs feature in Vendor/Seller Central.	Cost increases are not allowed. Use the Edit Item Costs feature in Vendor/Seller Central. If necessary you can use the `Skip Cost Price` attribute to remove the requirement for providing a Cost Price via the API.	To avoid this, use the `getListingsItem` API to surface existing costs. Also, submit cost increases through the 'Edit Item Costs' feature in Vendor/Seller Central for approval prior to submission via APIs where possible.
90225	Value for `attribute_name` is longer than the allowed maximum (limit unit).	Some attributes have a maximum limit on the length of the value that can be submitted. Trim down the length of the attribute value and try submitting again. Common attributes with the maximum number of characters permitted include: `item_name`: 200 characters `generic_keyword`: 250 bytes `included_components`: 80 characters `externally_assigned_product_identifier`: 12 characters expected for UPC, 13 for EANs, 14 for GTINs
4005013	The information provided matches an item that is already in your catalog (SKU: `matched_sku`; ASIN: `matched_asin`). Items cannot be duplicated in your catalog.	This issue is returned when an item is submitted and matches an existing ASIN that is already added to the account, or when a vendor wants to edit a SKU on an existing ASIN. A SKU is an un-editable attribute; after the item is created, it cannot be changed. The vendor needs to use the original SKU they used to create the item before editing any other attributes.	Build a workflow to surface any pre-existing catalog data for the SKU using the `getListingsItem` and `getCatalogItem` APIs.
90180	The value `Boolean \| [false, true]` in the field value for the attribute `attribute_name` has the wrong type. The provided type is `STRING` while the expected type is `BOOL`.	A solution would be resubmitting with the expected type referenced in the issue message. Example: The value `number` in the field `weight#1.value` for the attribute `battery` has the wrong type. The provided type is `STRING` while the expected type is `DECIMAL`.	To avoid this, add warnings within your system to advise on expected type for that value.
4005007	A match for the value of `attribute_name` could not be found for the brand specified. Correct the value and resubmit. If the value is correct, contact your vendor manager to provide documentation verifying affiliation between the value and brand specified.	This issue is returned when the item submitted has an external ID that is not registered for use with the provided brand. Make sure that you’re using the appropriate value (UPC, EAN, or GTIN). If correct, You will need to provide proof of affiliation between the company the External ID is registered to and the brand you selected (for example, a license agreement). You will need to submit the following information: Seller ID Screenshot of issue message or Submission ID or Batch ID. Exact Brand Name Title of the product UPC/EAN Marketplace GS1 Certificate for the UPC/EANs should be attached in the related Item.	Contact Us: Open a case to Developer Support if you require technical support or where indicated in the troubleshooting guide.
90244	Invalid enumerated value `value` for attribute `attribute_name`.	This issue means the provided value for the attribute is not valid. Certain attributes have hard enumerated values which the provided value must match exactly. Ensure you are calling the latest version of the Product Type Definitions API and confirm that the Product Type in the JSON payload is correct. If this issue still remains unresolved, you can always submit a ticket to Developer Support.	Reference the Product Type Definitions API for a list of permitted values and ensure that they are reflected in your system to prevent failed submissions.
4005033	The value for `attribute_name` cannot be edited. Revert the value to `original_value` and resubmit.	This issue is returned when you attempt to modify an un-editable attribute. The attribute value should be changed back to the original provided in the issue message. If the original value is incorrect and you wish to have the value updated, then a Contact Us case should be submitted providing the following: A list of UPCs/EANs The attribute name to be changed The new value There can also be edge cases where the original value is no longer be accepted upon resubmission. If this is the case, you should also submit a Contact Us case.	Build a workflow to surface any pre-existing catalog data for the SKU using the `getListingsItem` and `getCatalogItem` APIs.
90248	The field `field` for the attribute `attribute_name` does have too many values. The allowed maximum is `allowed_count` value(s), but there are currently `actual_count` values.	The field specified has more values than allowed. This is most commonly associated with Apparel size attributes where values are dependent on Product Type. Example: `bottoms_size` not expected for `shirt` Product Type. To solve this, remove or reduce the values depending on the issue message.	To avoid this, add restrictions so that only relevant Apparel Size Attributes for a particular Product Type can be selected. Add pre-validation checks for others such as currency where only one value is expected.
90114	Value for `attribute_name` is less than the required minimum `limit`.	This issue occurs when the acceptable minimum limit on the integer or decimal attribute value is not met. Typically this issue is seen with cost price, case pack quantity and `items_per_inner_pack`. Ask the vendor to review the issue message and correct the submission by entering a minimum value. Example: Cost price is expected to be greater than zero so this entry would return an issue. cost_price: [{ "currency" : "GBP", "value" : 0 }]	To avoid this, add pre-validation check or warning if provided value is less than the required minimum.
90193	A `left_attribute_name` value `left_attribute_value` is not less than `right_attribute_name` value `right_attribute_value`.	Example: A `cost_price` value '126.1' is not less than `list_price` value '33.21'.	To avoid this, provide a value lower than the `right_attribute_value`.
90147	A `left_attribute_name` value `left_attribute_value` is not less than or equal to `right_attribute_name` value `right_attribute_value`.	Provide a value less than or equal to the `right_attribute_value` mentioned in the issue message. This is most commonly due to `item_weight` being less than `item_package_weight`. Example: An `item_weight#1.value` value `3.4` is not less than or equal to `item_package_weight#1.value` value `6d-1`.	Add pre-validation checks within your system to flag if the `item_weight` is less or equal to `item_package_weight` so the vendor can take corrective action prior to submission.
90221	Value `value` for `attribute_name` should be greater than the limit `limit`.	This issue is typically returned when a value of `0` for weight or cost has been submitted. Example: Value `0` for `item_package_weight` should be greater than the limit `0`.	To avoid this, add warnings where the value entered is lower than the given threshold value. Values for cost and weight must be greater than zero.
4005015	The ASIN provided does not match the existing item in the Amazon catalog. Please replace the value with one of the following and resubmit: `attribute_value`.	This issue is returned when the Amazon Matching Service found a different ASIN in the catalog instead of the Merchant Suggested ASIN attribute value provided. You will need to enter the matched ASIN referenced in the issue message in the Merchant Suggested ASIN column. Any typo will return an Invalid ASIN Error. Note: Ask the vendor to provide the value of the Merchant Suggested ASIN in upper case.	Build a workflow to surface any pre-existing catalog data for the SKU using the `getListingsItem` and `getCatalogItem` APIs.
4005008	The value of `attribute_name` is either restricted or not registered in GS1. Contact Amazon to provide the relevant GS1 certificate.	This issue is returned when an external product ID is either restricted or not registered in GS1. If you have proof of ownership of the product, contact Amazon to provide the relevant GS1 certificate.	Check that the UPC/EAN/GTIN you supplied is correct.
99016	A maximum of `max_count` occurrence(s) is/are allowed for the attribute `attribute_name` but it currently occurs `actual_count` times.	This occurs when there are too many entries for a certain attribute name. A solution would be to remove any additional entries and resubmit. If the issue persists, contact Developer Support to request that they delete the duplicate attributes. Example: A maximum of two occurrence are allowed for the attribute `sport_type` but it currently occurs four times. In order to fix this, the vendor should remove two of the entries: "sport_type": [{ "language_tag", "en_GB", "value" : "Multi-Sport" }, { "language_tag" : "en_GB", "value" : "Surfing" }, { "language_tag" : "en_GB", "value" : "Snowboarding"}, { "language_tag" : "en_GB", "value" : "Cycling" }]	To avoid this, add pre-validation check or warnings if you supply more entries than allowed.
90188	Value does not satisfy ISBN/UCCID. Checksum requirements for attribute `attribute_name`.	The External Product ID attribute value provided is invalid. Each `external_id_type` has an expected number of characters. Review and correct so that they match the following requirements: 12 characters expected for UPC, 13 characters expected for EANs, 14 characters expected for GTINs.	To avoid this, add a warning within your system if the convention is violated. Example: UPC selected as type but the identifier has 13 characters rather than the 12 expected.
90226	Value for `attribute_name` is shorter than the allowed minimum (limit unit).	This issue is returned when submitted values are shorter than a given minimum. To solve this, correct the value and resubmit. Example: Value for `short_item_name` is shorter than the required minimum (`X` characters). Most common examples of this include where the value for `externally_assigned_product_identifier` is shorter than the allowed minimum.	To avoid this, apply restrictions or warnings to values in your system where there are known allowed minimums.
4005022	The package dimensions of the item must be smaller than the package dimensions of the package hierarchy containing the item.	The submitted package dimension values (width, height, length, weight) cannot be greater than the values for its parent product.	To avoid this, compare the dimension values with the parent product, and fix the values so that they are consistent across the hierarchy.
4005001	The provided currency for `attribute_name` does not match with the existing currency for this item.	Currency does not match for this ASIN.	Contact Us: Open a case to Developer Support if you require technical support or where indicated in the troubleshooting guide.
90194	Value does not meet pattern constraint for attribute `attribute_name`. Value should match the pattern `pattern`.	Example: Value for `[fabric_type]` does not meet pattern: <percentage value>% <fabric name>, for example, 100% cotton.	To avoid this, provide the value in the given pattern in the issue message.
4005018	Luxury brand products require a luxury or professional product category.	This is a luxury brand product. A product category starting with `Luxury` or `Professional` should be selected. If you feel that your brand is not a luxury brand, contact your Amazon point of contact.	To avoid this, select a `Luxury` Product Type.
90197	Value for `attribute_name` is greater than the allowed maximum `limit`.	The issue occurs when maximum limit on the integer or decimal attribute value which is acceptable is not met. Example: Value for `[manufacturer_minimum_age]` is greater than the allowed maximum (1188)	To avoid this, decrease the value and try submitting again.
4005006	An item in your catalog already exists for the value of `attribute_name` and the value of `attribute_name` is not editable. For different products, resubmit with a different value.	This issue occurs when you try to edit the External Product ID value for an existing item that the vendor already has in their account. External product ID field is non-editable after the item is created. You will need to provide the original External Product ID to continue editing the item.	Build a workflow to surface any pre-existing catalog data for the SKU using the `getListingsItem` and `getCatalogItem` APIs.
4005019	Non-luxury brands cannot be submitted for a luxury or professional product category.	The Selling Partner attempted to list a non-luxury beauty brand under a luxury beauty category. Ask the Selling Partner to pick a product category other than `Luxury` or `Professional`.	If Selling Partners want to sell under the Luxury Beauty category, ask them to work directly with their Amazon Vendor Managers to enable this category for them.
4000000	An internal error has occurred. Please try again.	There was an internal failure and we could not communicate further details about the issue.	If the issue persists after two trial attempts, cut a ticket to Customer Support.
90199	Value for `attribute_name` must not contain HTML tags.	An HTML tag cannot be included in this field. To solve this, enter a value that does not include an HTML tag.	To avoid this, add pre-validation check or warning if provided value contains HTML tags.
4005039	You have multiple submissions for this item. In order to edit one of them, please contact Amazon Support.	There are multiple contributions within the catalog for this item. Raise a Contact Us case via Vendor Central if you're a vendor or Developer Support if you're a seller that states: The issue encountered The list of affected EANs/UPC SKUs and vendor code.	Requires Amazon Support to resolve.
90196	Value for `attribute_name` must not contain a URL.	A URL cannot be included in this field. To solve this, enter a value that does not include a URL.	To avoid this, add a pre-validation check or warning if provided value contains URL.
4005038	The product ID you provided differs from one that you previously provided for the same SKU. Please provide the original product ID.	This issue occurs because a different `external_id` has been assigned to an existing SKU. If you still needs to update this external product ID (a non-editable attribute), you will need to contact Amazon Support.	Build a workflow to surface any pre-existing catalog data for the SKU using the `getListingsItem` and `getCatalogItem` APIs.
4005002	The value of `attribute_name` decreased by more than the maximum allowed value. Reduce the value by a lesser amount and resubmit.	This issue occurs because any drastic decrease in cost price is not allowed. You should review the cost prices in case of issues. You can also use the `Skip Cost Price` attribute to remove the requirement for providing a Cost Price. If you do want to amend your cost prices, either contact your Amazon point of contact or submit a case via Amazon Support with ASIN/EAN old price, new price and currency.	To avoid this, use the `getListingsItem` API to surface existing costs
4005003	The value of `attribute_name` cannot be greater than the list price.	Entered cost price is greater than the list price.	To avoid this, provide the cost price less than the list price.
4000002	A value for `attribute_name` is required.	A required value for a specified attribute is missing. Provide the required value for the missing attribute as specified in the issue message.	Amazon makes frequent updates to PT schemas. Integrators and Selling Partners need to stay updated with the latest requirements in order to prevent this issue. This can be done as follows: Implement the Notifications API: `notification_type` `PRODUCT_TYPE_DEFINITIONS_CHANGE` to know about when the updates happen. Refresh the schema on your end to pull the latest from the Product Type Definitions API and identify required and conditionally required attributes and add them to validation checks. Pre-release versions of product type definitions can be retrieved with `release_candidate`.
4000003	The Amazon Product Type specified is invalid or not supported.	The Amazon Product Type specified is invalid or not supported. The Product Type Definitions `searchDefinitionsProductTypes` operation should be used to verify that the Product Type is valid. Note: the Product Type Definitions `getDefinitionsProductType` operation will "roll up" to parent product types and return a 200 response for unlaunched PTs. If this happens the Product Type Definitions Get API response will have the `productType` attribute set to the parent PT, usually `PRODUCT`.	For selling partners, select a valid Product Type. For vendors, ensure that you are authorized to sell for that Product Type prior to making the submission, as stated in Step 1 of the Product Type Definitions Use Case Guide.
4005035	The provided vendor code is not eligible to sell this brand. Contact your vendor manager for approval.	The vendor's vendor code is not authorized to sell this brand. To solve this, contact your Amazon point of contact.	The provided vendor code is not eligible to sell this brand. Contact your vendor manager for approval.
4005012	The provided value for `attribute_name` and vendor code are assigned to a different ASIN.	The SKU is already assigned to a different ASIN. A single vendor code + SKU can be assigned to only one ASIN. Raise a Contact Us case to Amazon to support with resolution.	Build a workflow to surface any pre-existing catalog data for the SKU using the `getListingsItem` and `getCatalogItem` APIs.
18280	Value of `attribute_name` does not contain a percentage (for example, Cotton instead of 100% Cotton).	This issue occurs when the selling partner has not provided a `fabric_type` in the expected format or when there is already a bad `fabric_type` value in the Contribution Catalog.	If the selling partner provided the `fabric_type` attribute in their request, have them correct the format to include the percent sign. If the selling partner did not provide the `fabric_type` attribute in their request and they do not want to set it, you can correct the issue by deleting this attribute from the contribution.

Updated about 1 month ago