Overview

Amazon has upgraded the Selling Partner API (SP‑API) Listings Items endpoint to return detailed throttle information when a request exceeds a rate limit. Effective January 25 2025, the change applies to both the v2020‑09‑01 and v2021‑08‑01 versions, giving developers precise insight into which limit tier caused the block. Sellers and developers need to adjust error handling to take advantage of the new data and avoid unnecessary delays.

Key Points

• Tier‑specific error codes — The putListingsItem and patchListingsItem operations now include the exact limit tier (e.g., per‑item, account‑wide) that triggered throttling, instead of a generic “Rate limit exceeded” message.
• Both API versions covered — The enhancement is rolled out for the 2020‑09‑01 and 2021‑08‑01 Listings Items APIs, so existing integrations receive the benefit without code migration.
• Improved bottleneck visibility — Developers can differentiate between a per‑SKU cap (e.g., 10 updates per minute for a single ASIN) and a global account ceiling (e.g., 5,000 updates per hour).
• Actionable retry data — The response payload now supplies fields that indicate the remaining quota and reset time for the specific tier, enabling smarter back‑off strategies.
• No change to limit values — Amazon has not altered the numerical thresholds; it has only added transparency around why a request was rejected.

How the Granular Throttle Details Work

1. Request submission — A seller’s integration sends a PUT /listings/2020-09-01/items call to update price or inventory for ASIN B07XYZ.
2. Limit evaluation — Amazon checks the request against all active throttling tiers (per‑item, per‑account, per‑region). If any tier is exceeded, the call is rejected.
3. Detailed error response — The API returns a 429 Too Many Requests response that includes a JSON block such as:

   {
     "errorCode": "RateLimitExceeded",
     "throttleTier": "PER_ITEM",
     "retryAfterSeconds": 30,
     "quotaRemaining": 0,
     "quotaResetTimestamp": 1706505600
   }
   

   This tells the client that the per‑item limit was hit, that no quota remains, and that the limit will reset in 30 seconds.