Enhance get_items to handle large requests and expose partial errors

CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.4.0] - 2026-09-04
+
+### Added
+
+- `availability` parameter in `search_items` to include the items that are out of stock
+- `host` and `auth_endpoint` parameters in `AmazonCreatorsApi` and `AsyncAmazonCreatorsApi` to replace the endpoints of the API, useful to run tests against a mock server
+- `get_asin` and `errors` are available directly in `amazon_creatorsapi`
+- The identifier that Amazon gives to a request is part of the message of the error, so it can be reported to Amazon support
+- `py.typed` marker, so the type hints of the package are used by type checkers
+
+### Changed
+
+- `search_items` rejects a search without any criteria instead of sending it to the API
+- `AsyncAmazonCreatorsApi` builds its requests with the models of the SDK, so both clients validate the same values before sending a request
+- Every client uses its own configuration for the SDK instead of the one shared by the whole process
+- Throttling is measured with a monotonic clock and is safe to use from several threads
+
+### Fixed
+
+- Examples in the documentation that used names that do not exist, such as `SortBy.PRICE_LOW_TO_HIGH` or `GetItemsResource.ITEMINFO_TITLE`
+- Documented limits of `item_count`, `min_reviews_rating` and `variation_page`, which did not match the ones accepted by the API
+
+### Removed
+
+- `six` dependency, which was not used
+
+## [7.3.0] - 2026-09-03
+
+### Added
+
+- `retries` parameter in `AmazonCreatorsApi` and `AsyncAmazonCreatorsApi` to retry the throttled and failed requests that Amazon asks to retry, waiting longer before every attempt and honouring the `Retry-After` header
+- `AccessDeniedError`, raised when the credentials cannot perform the requested operation
+- `ResourceNotFoundError`, raised when a feed or report does not exist, telling it apart from missing items
+
+### Changed
+
+- Errors are mapped from the response of the Creators API instead of the codes of the old Product Advertising API, so the reason and the fields that failed are part of the message
+- A rejected request raises `InvalidArgumentError`, missing or expired credentials raise `AuthenticationError` and a forbidden request raises `AccessDeniedError`, instead of a generic `RequestError`
+- An expired token is refreshed once and the request is sent again instead of failing
+- Connection failures and unparseable responses raise `RequestError` instead of leaking the errors of the HTTP client
+
+## [7.2.0] - 2026-09-03
+
+### Added
+
+- `get_items` splits a request with more items than the API accepts into as many calls as needed, so any amount of items can be requested at once
+- `include_unavailable` parameter in `get_items` to get an item holding only the ASIN for every requested item missing from the response
+- Partial errors of a response are available in the `errors` attribute of the lists returned by `get_items` and `get_browse_nodes`, and are reported in the message of `ItemsNotFoundError`
+- `ErrorData` and `ResultList` available in `amazon_creatorsapi.models`
+
+### Changed
+
+- `get_items` returns the items in the order they were requested, and asks for duplicated items only once
+- `AmazonCreatorsApi` applies the timeout to the OAuth2 token refresh as well, which previously waited indefinitely, and reports its failures as `AuthenticationError`
+- `AmazonCreatorsApi` validates the version when it is created, as `AsyncAmazonCreatorsApi` already did, instead of failing on the first request
+- Values rejected by the API constraints raise `InvalidArgumentError` instead of a `pydantic.ValidationError`
+- `get_items` raises `ItemsNotFoundError` when the response holds no items, as documented, instead of returning an empty list
+
 ## [7.1.0] - 2026-09-03
 
 ### Added

README.md

@@ -60,6 +60,29 @@ for item in items:
     print(item.images.primary.large.url)
 ```
 
+Items come back in the order they were requested, duplicates are asked for
+only once, and requests with more items than the API accepts at once are
+split into as many calls as needed, so any amount of items can be requested:
+
+```python
+items = api.get_items(asins)  # Any amount of items, split into several calls
+```
+
+Amazon can answer with only some of the requested items, describing the
+missing ones as partial errors. Those errors are available in the returned
+list, and unavailable items can be included as an item holding only the ASIN:
+
+```python
+items = api.get_items(["B01N5IB20Q", "0000000000"], include_unavailable=True)
+
+for error in items.errors:
+    print(error.code, error.message)
+
+for item in items:
+    if item.item_info is None:
+        print(f"{item.asin} is not available")
+```
+
 ### Search Products
 
 ```python
@@ -68,6 +91,17 @@ for item in results.items:
     print(item.item_info.title.display_value)
 ```
 
+A search needs at least one of `keywords`, `actor`, `artist`, `author`, `brand`, `title`, `browse_node_id` or `search_index`, and only returns the items available for purchase unless asked otherwise:
+
+```python
+from amazon_creatorsapi.models import Availability
+
+results = api.search_items(
+    keywords="nintendo switch",
+    availability=Availability.INCLUDEOUTOFSTOCK,
+)
+```
+
 ### Get Product Variations
 
 ```python
@@ -149,7 +183,58 @@ amazon = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, timeout=10)  # Fai
 amazon = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, timeout=0.5)  # Fails after half a second
 ```
 
-It applies to every API request. In `AmazonCreatorsApi` the OAuth2 token refresh is handled by the bundled SDK and is not covered by this value, while `AsyncAmazonCreatorsApi` applies it to the token refresh as well.
+It applies to every API request, including the OAuth2 token refresh.
+
+### Retries
+
+Amazon asks clients to back off and try again when it throttles a request or fails to serve it. The client does that on its own, waiting longer before every attempt and honouring the `Retry-After` header when the API sends it. An expired token is refreshed once and the request is sent again.
+
+```python
+amazon = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, retries=5)  # Up to 5 extra attempts
+amazon = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, retries=0)  # Fail on the first error
+```
+
+### Custom Endpoints
+
+The base URL of the API and the one used to get the OAuth2 token can be replaced, which is useful to run the tests of a project against a mock server:
+
+```python
+api = AmazonCreatorsApi(
+    ID,
+    SECRET,
+    VERSION,
+    TAG,
+    COUNTRY,
+    host="http://localhost:8080",
+    auth_endpoint="http://localhost:8080/token",
+)
+```
+
+### Error Handling
+
+Every error raised by the library inherits from `AmazonCreatorsApiError`, so a single `except` covers them all. The message carries the reason given by Amazon, the fields that failed validation and the identifier of the request, which is what Amazon support asks for:
+
+| Exception | Raised when |
+| --- | --- |
+| `InvalidArgumentError` | An argument is not valid or the request is rejected by Amazon |
+| `AssociateValidationError` | The credentials are not valid for the selected marketplace |
+| `AuthenticationError` | The credentials are missing, invalid or expired |
+| `AccessDeniedError` | The credentials cannot perform the requested operation |
+| `ItemsNotFoundError` | No items are found for the request |
+| `ResourceNotFoundError` | The requested feed or report does not exist |
+| `TooManyRequestsError` | The rate limit is exceeded and the retries are exhausted |
+| `RequestError` | The request fails for any other reason |
+
+```python
+from amazon_creatorsapi.errors import AmazonCreatorsApiError, ItemsNotFoundError
+
+try:
+    items = api.get_items(["B01N5IB20Q"])
+except ItemsNotFoundError:
+    print("The item is not available")
+except AmazonCreatorsApiError as error:
+    print(error)
+```
 
 ### Async Support
 
@@ -204,11 +289,17 @@ from amazon_creatorsapi.models import (
 items = api.get_items(["B01N5IB20Q"], condition=Condition.NEW)
 
 # Use SortBy enum for search ordering
-results = api.search_items(keywords="laptop", sort_by=SortBy.PRICE_LOW_TO_HIGH)
+results = api.search_items(
+    keywords="laptop",
+    sort_by=SortBy.PRICE_COLON_LOW_TO_HIGH,
+)
 
 # Specify which resources to retrieve
 from amazon_creatorsapi.models import GetItemsResource
-resources = [GetItemsResource.ITEMINFO_TITLE, GetItemsResource.OFFERS_LISTINGS_PRICE]
+resources = [
+    GetItemsResource.ITEM_INFO_DOT_TITLE,
+    GetItemsResource.OFFERS_V2_DOT_LISTINGS_DOT_PRICE,
+]
 items = api.get_items(["B01N5IB20Q"], resources=resources)
 ```
 

amazon_creatorsapi/__init__.py

@@ -4,8 +4,8 @@
 """
 
 __author__ = "Sergio Abad"
-__all__ = ["AmazonCreatorsApi", "Country", "models"]
+__all__ = ["AmazonCreatorsApi", "Country", "errors", "get_asin", "models"]
 
-from . import models
+from . import errors, models
 from .api import AmazonCreatorsApi
-from .core import Country
+from .core import Country, get_asin