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:
|
|
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:
|
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:
|
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:
|
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 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