> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/errors.md).

# 06. Error Reasons (reason)

### **How Errors Are Delivered**

**Branch on the `reason` string.** The error object provides the game with two values, `e.reason` (for branching) and `e.message` (for logging). **Numeric error codes are not delivered.**

<table><thead><tr><th width="300">API Type</th><th>Error Delivery Form</th></tr></thead><tbody><tr><td>Lifecycle and other APIs (<code>initializeAsync</code> · <code>startGameAsync</code> · <code>openDeeplink</code>)</td><td>Promise reject. Error object with <code>e.reason</code> (reason) · <code>e.message</code> (message for logging)</td></tr><tr><td>Ad APIs (<code>showRewardedAsync</code> · <code>showInterstitialAsync</code>)</td><td>Resolves with <code>{ status: "failed", reason }</code> instead of rejecting (see <a href="https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/iaa.md">04. In-App Advertising (IAA)</a>)</td></tr><tr><td>Purchase and product details APIs (<code>iap.purchase</code> · <code>iap.getProductDetailsAsync</code>)</td><td>Resolves with a result object on success; <strong>failure and cancellation are Promise rejects</strong> with <code>e.reason</code> · <code>e.message</code> (see 'Purchase and Product Details Errors' below). An empty array from product details lookup is a normal resolve, not a failure (see <a href="https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/iap.md">05. In-App Purchase (IAP)</a>)</td></tr></tbody></table>

The game decides the text shown to end users based on `reason`. `message` is an auxiliary string for logging and debugging and must not be used as a branching condition.

### **Common Errors**

| reason                   | description                                                                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| invalid\_params          | Missing required parameter · format error · value out of range                                                                                                                                           |
| unsupported\_action      | A request this app version cannot handle                                                                                                                                                                 |
| platform\_not\_supported | A feature not provided in this environment or app version. The SDK decides this without asking the app. Both running in a regular browser and an app version that does not provide the feature fall here |
| user\_cancelled          | Cancelled by the user. Do not show an error popup; return to the original flow                                                                                                                           |
| rate\_limited            | Call rate limit exceeded. Do not call again immediately                                                                                                                                                  |
| timeout                  | No result within the time limit of the action                                                                                                                                                            |
| internal\_error          | Any other internal processing failure. Treat unknown reasons the same way                                                                                                                                |

### **Ad-Specific Errors**

| reason              | description                                                                                                                                                                                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| invalid\_request    | Missing required parameter · unregistered placement ID · placement type mismatch. If `placementId` or the rewarded ad's `requestId` is missing, the SDK fails immediately with this reason without calling the app                                                                                                               |
| unsupported\_screen | Called from a screen that does not support ads                                                                                                                                                                                                                                                                                   |
| not\_initialized    | Ad SDK initialization not complete                                                                                                                                                                                                                                                                                               |
| no\_fill            | No ad to show. **Not eligible for a reward.** Provide an alternative path to continue without an ad                                                                                                                                                                                                                              |
| show\_failed        | Ad display failed (including cases where it closed before playback started, or the request arrived while the screen was covered)                                                                                                                                                                                                 |
| timeout             | Timeout occurred (the ad may still be shown after the error). Use the returned `requestId` to guard against duplicate rewards                                                                                                                                                                                                    |
| already\_showing    | Called again while an ad is playing · ad request while a payment is in progress                                                                                                                                                                                                                                                  |
| network\_error      | Communication layer failure                                                                                                                                                                                                                                                                                                      |
| ad\_opt\_out        | The user has opted out of ads. In the ONE store global app, ads are not served to users who have turned on the ad opt-out setting. Handle it the same way as `no_fill`. **Not eligible for a reward.** Provide an alternative path to continue without an ad. Requesting again returns the same result until the setting changes |

### **SDK-Determined Errors**

The SDK determines the errors below on its own, without calling the app.

| reason                   | description                                                                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| sdk\_not\_initialized    | An API that requires ordering (such as `startGameAsync`) was called before `initializeAsync()` completed                              |
| platform\_not\_supported | A feature not provided in this environment or app version was called (e.g. an ad request in an app version that does not support ads) |

### **Purchase and Product Details Errors**

*Both APIs share the same set of error reasons.*

| reason                   | description                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| invalid\_request         | Missing required parameter · format error · `developerPayload` exceeds 200 bytes · the product ID list for product details lookup is empty, contains an empty string, or exceeds 20 items · the payment module judged the request invalid                                                                                                                                                        |
| user\_cancelled          | The user cancelled the payment                                                                                                                                                                                                                                                                                                                                                                   |
| service\_unavailable     | Device or server network error · error during purchase processing                                                                                                                                                                                                                                                                                                                                |
| already\_owned           | Already owned in an unconsumed state (repurchase before consumption)                                                                                                                                                                                                                                                                                                                             |
| payment\_failed          | Payment failed. Check payment eligibility and payment method                                                                                                                                                                                                                                                                                                                                     |
| need\_login              | Not logged in to the store app                                                                                                                                                                                                                                                                                                                                                                   |
| security\_error          | Abnormal app payment request · required permission request cancelled                                                                                                                                                                                                                                                                                                                             |
| already\_processing      | Payment request while a payment or ad UI is displayed (full-screen UIs cannot be displayed simultaneously). Product details lookup does not cover the screen, so it is not subject to this restriction                                                                                                                                                                                           |
| need\_update             | ONE store service app not installed or outdated. Guide the user to update the app                                                                                                                                                                                                                                                                                                                |
| timeout                  | Product details lookup did not respond within 10 seconds. Try again shortly. Does not apply to payments                                                                                                                                                                                                                                                                                          |
| internal\_error          | Any other internal processing failure                                                                                                                                                                                                                                                                                                                                                            |
| platform\_not\_supported | Purchases or product details lookup are not provided in this environment or app version. The SDK decides this without asking the app. Both running in a regular browser and an app version that does not support the feature fall here. After `initializeAsync()`, check in advance with `sdk.iap.isSupported()` for payments and `sdk.iap.isSupported("getProductDetails")` for product details |
