Regions, Pagination, and Errors
Request conventions for regional data, paginated lists, and error handling.
Several endpoints return region-specific store data. Region-aware routes accept ISO-style country or locale inputs depending on the endpoint.
Regions
Use store regions consistently across a request flow. Price and promotion results can differ by region, currency, availability, and local catalog rules.
Common region examples:
| Region | Store context |
|---|---|
US | United States |
GB | United Kingdom |
DE | Germany |
FR | France |
ES | Spain |
If a region is unsupported or unavailable, routes may fall back to a default region or return an empty result, depending on the endpoint.
Free-game promotion routes normalize availability metadata for clients. countriesBlacklist is always an array, giveaway.offerId is always present, and giveaway.platform is a string for platform-specific promotions or null otherwise.
Localization
REST endpoints that return public offer DTOs accept a locale query parameter. GraphQL offer fields accept a locale argument. Missing or blank locale values default to en-US.
Offer localization uses exact locale matches only. For example, locale=es-MX checks only es-MX; it does not fall back to es-ES or another regional variant. If no matching localization record exists for an offer, the response keeps the canonical en-US offer text for that offer.
Only public offer text and content fields are localized: title, description, longDescription, developerDisplayName, publisherDisplayName, seller, tags, offerMappings, productSlug, urlSlug, and url. Prices, availability, countries, assets, builds, manifests, binary sizes, reviews, and other operational data remain canonical.
Each offer includes localization metadata:
| Field | Meaning |
|---|---|
locale | Requested locale used for the offer response |
localeStatus | canonical for en-US, localized when an exact localization record was applied, or fallback when canonical text was returned for a non-canonical locale |
canonicalLocale | en-US on non-canonical responses |
localization | Metadata from the applied localization record when localeStatus is localized |
For nested GraphQL offer fields such as related and suggestions, the parent offer locale is reused when the nested field does not provide its own locale argument.
Pagination
Paginated endpoints use query parameters such as page, limit, offset, or route-specific cursors. Prefer the names documented on each OpenAPI operation.
Keep page sizes conservative. Large responses increase API latency and can be harder for clients to cache safely.
Errors
Error responses use HTTP status codes and a JSON body when the route can provide one.
| Status | Meaning |
|---|---|
400 | Invalid query string, path parameter, or request body |
401 | Authentication required or token rejected |
403 | Authenticated client cannot access the resource |
404 | Resource was not found |
429 | Rate limit exceeded |
500 | Unexpected server error |
Clients should branch on the HTTP status first and treat the response body as diagnostic detail.