在 Flutter SDK 中处理错误

SDK 返回的所有错误均为 AdaptyErrorCode 类型。示例如下：

Tip

调试前请先开启详细日志。 大多数 AdaptyError 都包含来自 StoreKit、Play Billing、网络或后端的底层错误。开启详细日志后（await Adapty().setLogLevel(AdaptyLogLevel.verbose) — 参见日志记录），该底层错误会打印到控制台，通常能直接告诉你问题的根本原因。

Important

如果以上方案未能解决你的问题，请在联系支持团队之前查阅其他问题，按照其中的步骤操作，以便我们更高效地为你提供帮助。

    try {
      final result = await adapty.makePurchase(product: product);
    } on AdaptyError catch (adaptyError) {
      if (adaptyError.code == AdaptyErrorCode.paymentCancelled) {
        // Cancelled
      }
    } catch (e) {
    }

系统 StoreKit 代码

错误	代码	解决方案
unknown	0	表示发生了未知或意外错误。请重试，或参阅其他问题部分。
clientInvalid	1	表示客户端不被允许执行所尝试的操作。
paymentCancelled	2	表示用户取消了支付请求。无需采取任何操作，但从业务逻辑角度来看，你可以向用户提供折扣，或稍后再次提醒。
paymentInvalid	3	表示某个支付参数未被 App Store 识别。
paymentNotAllowed	4	表示该用户不被允许授权支付。
storeProductNotAvailable	5	表示所请求的产品在商店中不可用。请尝试重新安装应用。
cloudServicePermissionDenied	6	表示用户未授权访问云服务信息。
cloudServiceNetworkConnectionFailed	7	表示设备无法连接到网络。
cloudServiceRevoked	8	表示用户已撤销对该云服务的使用权限。
privacyAcknowledgementRequired	9	表示用户尚未确认 Apple 的隐私政策。
unauthorizedRequestData	10	表示应用正在尝试使用其不具备所需权限的属性。
invalidOfferIdentifier	11	优惠 `identifier` 无效。例如，你尚未在 App Store 中设置该标识符对应的优惠，或该优惠已被撤销。请确保在 AppStore Connect 中配置了所需的优惠，并传入有效的优惠标识符。
invalidSignature	12	表示支付折扣中的签名无效。
missingOfferParams	13	表示支付折扣中缺少必要参数。
invalidOfferPrice	14	表示你在 App Store Connect 中指定的价格已不再有效。优惠价格必须始终低于原价。

自定义 Android 代码

错误	代码	解决方案
adaptyNotInitialized	20	你需要通过 `Adapty.activate` 方法正确配置 Adapty SDK。了解如何为 Flutter 配置。
productNotFound	22	此错误表示请求购买的产品在商店中不可用。
invalidJson	23	付费墙 JSON 格式无效，请在 Adapty 看板中修复。详情请参阅使用远程配置自定义付费墙。
currentSubscriptionToUpdateNotFoundInHistory	24	未找到需要续订的原始订阅。
pendingPurchase	25	此错误表示购买状态为待处理而非已完成。详情请参阅 Android 开发者文档中的处理待处理交易页面。
billingServiceTimeout	97	此错误表示请求在 Google Play 响应之前已达到最大超时时间。例如，Play Billing Library 调用所请求的操作执行延迟可能导致此问题。
featureNotSupported	98	当前设备上的 Play Store 不支持所请求的功能。
billingServiceDisconnected	99	此致命错误表示客户端应用通过 `BillingClient` 与 Google Play Store 服务的连接已断开。
billingServiceUnavailable	102	此瞬态错误表示 Google Play 结算服务当前不可用。大多数情况下，这意味着客户端设备与 Google Play 结算服务之间的某处存在网络连接问题。
billingUnavailable	103	此错误表示购买过程中发生了用户结算错误。可能发生此错误的情形包括： 1. 用户设备上的 Play Store 应用版本过旧。 2. 用户所在国家/地区不受支持。 3. 用户为企业用户，且其企业管理员已禁止用户进行购买。 4. Google Play 无法扣款用户的付款方式，例如用户的信用卡可能已过期。 5. 用户未登录 Play Store 应用。
developerError	105	这是一个致命错误，表示你以不正确的方式使用了某个 API。
billingError	106	这是一个致命错误，表示 Google Play 本身存在内部问题。
itemAlreadyOwned	107	该消耗型商品已被购买。
itemNotOwned	108	此错误表示对该商品请求的操作失败，因为用户尚未拥有该商品。

自定义 StoreKit 代码

错误	代码	解决方案
noProductIDsFound	1000	此错误表示您在付费墙中请求的产品在 App Store 中均无法购买，尽管它们已在 App Store 中列出。此错误有时会伴随 `InvalidProductIdentifiers` 警告。如果只出现警告而没有错误，请忽略它。如果您遇到此错误，请按照修复 Code-1000 `noProductIDsFound` 错误部分中的步骤操作。
productRequestFailed	1002	当前无法获取可用产品。
cantMakePayments	1003	此设备不允许应用内购买。请参阅故障排查指南。
noPurchasesToRestore	1004	在 Adapty Flutter SDK 4.0.4 中已弃用：`restorePurchases()` 不再返回此错误。当没有可恢复的内容时，该方法会以当前用户画像成功完成，请检查其中的访问等级状态。在较早版本的 SDK 中，此错误表示 Google Play 未找到可恢复的购买记录。
cantReadReceipt	1005	设备上没有有效的收据。这可能是沙盒测试期间的问题。在沙盒环境中，在实际完成购买之前不会有有效的收据文件，因此请确保先进行一次购买再访问它。在沙盒测试期间，还要确保您在设备上使用了有效的 Apple 沙盒账号登录。
productPurchaseFailed	1006	产品购买失败。此错误封装了底层 StoreKit 错误——请查看封装的错误（或启用详细日志以在控制台中查看）以了解实际原因。封装的错误通常是上表中 StoreKit 代码 0–14 之一——最常见的是 `paymentCancelled`、`paymentInvalid`、`paymentNotAllowed` 或 `invalidOfferPrice`。如果无法确定具体原因，请尝试使用新的沙盒用户画像；如果仍然失败，请联系 Apple 支持。
refreshReceiptFailed	1010	此错误表示未收到收据。仅适用于 StoreKit 1。
receiveRestoredTransactionsFailed	1011	购买恢复失败。

自定义网络状态码

错误	代码	解决方案
notActivated	2002	Adapty SDK 未激活。最常见的原因是启动屏或早期 UI 钩子在 `Adapty().activate` 返回之前调用了 Adapty 方法。该问题时有时无，在模拟器上可能无法复现，因为真机的时序有所不同。请在调度任何其他 SDK 调用之前 `await` `activate` Future。完整调用顺序请参见 Flutter SDK 中的调用顺序。
badRequest	2003	请求错误。请确认您已完成与 App Store 集成所需的所有步骤。
serverError	2004	服务器错误。请稍后重试。如果问题仍未解决，请联系 Adapty 支持团队。
networkFailed	2005	该错误表示用户设备的网络连接存在问题。请尝试禁用 VPN，或在移动网络与 WiFi 之间切换。
decodingFailed	2006	该错误表示响应解码失败。请检查您的代码，确保发送的参数有效。例如，此错误可能表明您使用了无效的 API 密钥。
encodingFailed	2009	该错误表示请求编码失败。
analyticsDisabled	3000	由于您已选择退出，我们无法处理分析事件。
wrongParam	3001	该错误表示您的某些参数不正确。如果您正在使用 Adapty 付费墙编辑工具且因此错误无法显示付费墙，请在付费墙编辑工具中开启 Show on device。另一个可能的原因是本地备用付费墙文件版本与 SDK 版本不匹配，请在看板中下载新文件。
activateOnceError	3005	不能多次调用 `.activate` 方法。
profileWasChanged	3006	操作期间用户画像发生了变化。当 `Adapty().identify` 仍在执行时调用某个方法，就会发生这种情况——正在执行的调用会落在即将被替换的用户画像上，SDK 会将其拒绝。请在任何用户操作调用之前 `await` `identify`。请参见 Flutter SDK 中的调用顺序。
unsupportedData	3007	该错误表示 SDK 不支持该数据格式。
fetchTimeoutError	3101	该错误表示获取操作已超时。

自定义 UI 和插件代码

错误	代码	解决方案
jsException	4105	在运行付费墙编辑工具或用户引导时，JavaScript 抛出了异常。开启详细日志以查看底层 JavaScript 错误。
operationInterrupted	9000	此操作被系统中断。请重试调用。
emptyResult	10001	Flutter 插件从原生 SDK 收到了空结果。请重试调用，然后查看其他问题部分。
internalPluginError	10002	Flutter 插件发生内部错误。请查看其他问题部分。

其他问题

如果你还没有找到解决方案，可以尝试以下步骤：

升级 SDK 至最新版本：我们始终建议升级到最新版本的 SDK，因为它们更稳定，并包含已知问题的修复。
联系支持团队或在支持论坛中获取开发者社区的帮助。
通过 support@adapty.io 或在线聊天联系支持团队：如果您暂时无法升级 SDK，或升级后问题仍未解决，请联系我们的支持团队。请注意，如果您开启详细日志记录并将日志分享给团队，您的问题将得到更快解决。您也可以附上相关代码片段。