Xử lý lỗi trong Flutter SDK

Mọi lỗi được trả về bởi SDK đều là AdaptyErrorCode. Dưới đây là một ví dụ:

Tip

Bật verbose logs trước khi debug. Hầu hết các AdaptyError đều bao gồm một lỗi gốc từ StoreKit, Play Billing, mạng, hoặc backend. Khi bật verbose logs (await Adapty().setLogLevel(AdaptyLogLevel.verbose) — xem Logging), lỗi gốc đó sẽ được in ra console, thường cho biết nguyên nhân thực sự.

Important

Nếu các giải pháp này không khắc phục được vấn đề của bạn, hãy xem Các vấn đề khác để biết các bước cần thực hiện trước khi liên hệ bộ phận hỗ trợ, giúp chúng tôi hỗ trợ bạn hiệu quả hơn.

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

Mã StoreKit hệ thống

LỗiMãGiải pháp
unknown0Mã lỗi cho biết đã xảy ra lỗi không xác định hoặc không mong đợi.
Thử lại hoặc xem phần Các vấn đề khác.
clientInvalid1Mã lỗi này cho biết client không được phép thực hiện hành động đã thử.
paymentCancelled2

Mã lỗi này cho biết người dùng đã hủy yêu cầu thanh toán.

Không cần thực hiện hành động nào, nhưng về mặt logic nghiệp vụ, bạn có thể đề nghị giảm giá cho người dùng hoặc nhắc nhở họ sau.

paymentInvalid3Lỗi này cho biết một trong các tham số thanh toán không được App Store nhận dạng.
paymentNotAllowed4Mã lỗi này cho biết người dùng không được phép xác thực thanh toán.
storeProductNotAvailable5Mã lỗi này cho biết sản phẩm được yêu cầu không có sẵn trong cửa hàng.
Thử cài đặt lại ứng dụng.
cloudServicePermissionDenied6Mã lỗi này cho biết người dùng chưa cho phép truy cập thông tin dịch vụ Cloud.
cloudServiceNetworkConnectionFailed7Mã lỗi này cho biết thiết bị không thể kết nối mạng.
cloudServiceRevoked8Mã lỗi này cho biết người dùng đã thu hồi quyền sử dụng dịch vụ cloud này.
privacyAcknowledgementRequired9Mã lỗi này cho biết người dùng chưa xác nhận chính sách quyền riêng tư của Apple.
unauthorizedRequestData10Mã lỗi này cho biết ứng dụng đang cố sử dụng một thuộc tính mà nó không có quyền truy cập cần thiết.
invalidOfferIdentifier11

identifier của ưu đãi không hợp lệ. Ví dụ: bạn chưa thiết lập ưu đãi với identifier đó trên App Store, hoặc bạn đã thu hồi ưu đãi.

Hãy đảm bảo bạn đã thiết lập các ưu đãi mong muốn trong AppStore Connect và truyền một identifier ưu đãi hợp lệ.

invalidSignature12Mã lỗi này cho biết chữ ký trong payment discount không hợp lệ.
missingOfferParams13Mã lỗi này cho biết các tham số bị thiếu trong payment discount.
invalidOfferPrice14Mã lỗi này cho biết mức giá bạn đã chỉ định trong App Store Connect không còn hợp lệ. Các ưu đãi phải luôn thể hiện mức giá được giảm.

Mã Android tùy chỉnh

LỗiMãGiải pháp
adaptyNotInitialized20Bạn cần cấu hình Adapty SDK đúng cách bằng phương thức Adapty.activate. Xem hướng dẫn cho Flutter.
productNotFound22Lỗi này cho biết sản phẩm được yêu cầu mua không có sẵn trong cửa hàng.
invalidJson23JSON của paywall không hợp lệ. Hãy sửa trong Adapty Dashboard. Tham khảo chủ đề Tùy chỉnh paywall với Remote Config để biết cách khắc phục.
currentSubscriptionToUpdateNotFoundInHistory24Không tìm thấy gói đăng ký gốc cần gia hạn.
pendingPurchase25Lỗi này cho biết trạng thái mua hàng đang ở trạng thái chờ xử lý thay vì đã mua. Tham khảo trang Handling pending transactions trong tài liệu Android Developer để biết thêm chi tiết.
billingServiceTimeout97Lỗi này cho biết yêu cầu đã vượt quá thời gian chờ tối đa trước khi Google Play có thể phản hồi. Nguyên nhân có thể do chậm trễ trong quá trình thực thi hành động được yêu cầu bởi lệnh gọi Play Billing Library.
featureNotSupported98Tính năng được yêu cầu không được Play Store hỗ trợ trên thiết bị hiện tại.
billingServiceDisconnected99Lỗi nghiêm trọng này cho biết kết nối của ứng dụng khách đến dịch vụ Google Play Store qua BillingClient đã bị ngắt.
billingServiceUnavailable102Lỗi tạm thời này cho biết dịch vụ Google Play Billing hiện không khả dụng. Trong hầu hết các trường hợp, điều này có nghĩa là có sự cố kết nối mạng ở đâu đó giữa thiết bị khách và dịch vụ Google Play Billing.
billingUnavailable103

Lỗi này cho biết đã xảy ra lỗi thanh toán của người dùng trong quá trình mua hàng. Một số trường hợp có thể xảy ra bao gồm:

1. Ứng dụng Play Store trên thiết bị của người dùng đã lỗi thời.

2. Người dùng ở quốc gia không được hỗ trợ.

3. Người dùng là tài khoản doanh nghiệp và quản trị viên doanh nghiệp đã tắt quyền mua hàng của người dùng.

4. Google Play không thể tính phí phương thức thanh toán của người dùng. Ví dụ: thẻ tín dụng của người dùng có thể đã hết hạn.

5. Người dùng chưa đăng nhập vào ứng dụng Play Store.

developerError105Đây là lỗi nghiêm trọng cho biết bạn đang sử dụng API không đúng cách.
billingError106Đây là lỗi nghiêm trọng cho biết có vấn đề nội bộ với chính Google Play.
itemAlreadyOwned107Sản phẩm consumable này đã được mua trước đó.
itemNotOwned108Lỗi này cho biết hành động được yêu cầu trên mục đã thất bại vì

Mã StoreKit tùy chỉnh

LỗiMãGiải pháp
noProductIDsFound1000

Lỗi này cho biết không có sản phẩm nào bạn yêu cầu trên paywall có thể mua được trong App Store, dù chúng đã được liệt kê ở đó. Lỗi này đôi khi đi kèm với cảnh báo InvalidProductIdentifiers. Nếu cảnh báo xuất hiện mà không có lỗi, hãy bỏ qua nó.

Nếu bạn gặp lỗi này, hãy làm theo các bước trong phần Cách khắc phục lỗi Code-1000 noProductIDsFound.

productRequestFailed1002Không thể tải danh sách sản phẩm khả dụng vào lúc này.
cantMakePayments1003In-app purchase không được phép trên thiết bị này. Xem hướng dẫn khắc phục sự cố.
noPurchasesToRestore1004Không còn dùng nữa từ Adapty Flutter SDK 4.0.4: restorePurchases() không còn trả về lỗi này. Khi không có gì để khôi phục, phương thức hoàn tất thành công với hồ sơ người dùng hiện tại, vì vậy hãy kiểm tra trạng thái mức độ truy cập trong đó. Trong các phiên bản SDK cũ hơn, lỗi này cho biết Google Play không tìm thấy giao dịch mua để khôi phục.
cantReadReceipt1005

Không có receipt hợp lệ trên thiết bị. Điều này có thể xảy ra khi kiểm thử trong sandbox.

Trong sandbox, bạn sẽ không có file receipt hợp lệ cho đến khi thực sự thực hiện một giao dịch mua, vì vậy hãy đảm bảo bạn đã mua trước khi truy cập nó. Khi kiểm thử trong sandbox, hãy đảm bảo bạn đã đăng nhập trên thiết bị bằng tài khoản Apple sandbox hợp lệ.

productPurchaseFailed1006Mua sản phẩm thất bại. Lỗi này bao gồm một lỗi StoreKit bên trong — hãy đọc lỗi đó (hoặc bật verbose logs để xem trong console) để biết nguyên nhân thực sự. Lỗi bên trong thường là một trong các mã StoreKit 0–14 trong bảng trên — phổ biến nhất là paymentCancelled, paymentInvalid, paymentNotAllowed hoặc invalidOfferPrice. Nếu bạn không xác định được nguyên nhân cụ thể, hãy thử tạo hồ sơ sandbox mới; nếu vẫn thất bại, hãy liên hệ hỗ trợ Apple.
refreshReceiptFailed1010Lỗi này cho biết receipt không được nhận. Chỉ áp dụng cho StoreKit 1.
receiveRestoredTransactionsFailed1011Khôi phục giao dịch mua thất bại.
billingPlanUnavailable1060Chỉ dành cho iOS. Sản phẩm không cung cấp gói thanh toán được yêu cầu trên thiết bị này hoặc trong storefront này. Gói cam kết 12 tháng yêu cầu iOS 26.4 trở lên và ứng dụng được build bằng Xcode 26.5 trở lên. Yêu cầu SDK 4.3.0 trở lên.

Mã mạng tùy chỉnh

LỗiCodeGiải pháp
notActivated2002Adapty SDK chưa được kích hoạt.
Thường gặp nhất khi màn hình splash hoặc một UI hook sớm gọi các phương thức Adapty trước khi Adapty().activate trả về. Triệu chứng không cố định và có thể không tái hiện trên máy ảo vì thời gian thực thi trên thiết bị thật khác nhau. Hãy await Future activate trước khi lên lịch bất kỳ lệnh gọi SDK nào khác. Xem Thứ tự gọi trong Flutter SDK để biết toàn bộ trình tự.
badRequest2003Yêu cầu không hợp lệ.
Hãy đảm bảo bạn đã hoàn thành tất cả các bước cần thiết để tích hợp với App Store.
serverError2004Lỗi máy chủ.
Hãy thử lại sau một khoảng thời gian. Nếu vấn đề vẫn chưa được giải quyết, hãy liên hệ với đội hỗ trợ Adapty.
networkFailed2005Lỗi này cho biết có vấn đề với kết nối mạng trên thiết bị của người dùng.
Hãy thử tắt VPN hoặc chuyển sang WiFi từ mạng di động hoặc ngược lại.
decodingFailed2006Lỗi này cho biết quá trình giải mã phản hồi đã thất bại.
Xem lại code của bạn và đảm bảo rằng các tham số bạn gửi đi là hợp lệ. Ví dụ, lỗi này có thể cho biết bạn đang sử dụng API key không hợp lệ.
encodingFailed2009Lỗi này cho biết quá trình mã hóa yêu cầu đã thất bại.
analyticsDisabled3000Chúng tôi không thể xử lý các sự kiện analytics vì bạn đã tắt tính năng này.
wrongParam3001Lỗi này cho biết một số tham số của bạn không đúng.
Nếu bạn đang dùng Adapty paywall builder mà không hiển thị được paywall do lỗi này, hãy bật Show on device trong paywall builder.
Một nguyên nhân khả dĩ khác là phiên bản file fallback cục bộ không khớp với phiên bản SDK. Hãy tải file mới từ dashboard.
activateOnceError3005Không thể gọi phương thức .activate nhiều hơn một lần.
profileWasChanged3006Hồ sơ người dùng đã thay đổi trong quá trình thực hiện thao tác.
Điều này xảy ra khi một phương thức được gọi trong khi Adapty().identify vẫn đang chạy — lệnh gọi đang thực thi sẽ tác động lên một hồ sơ sắp bị thay thế và SDK từ chối nó. Luôn await identify trước bất kỳ lệnh gọi hành động người dùng nào. Xem Thứ tự gọi trong Flutter SDK.
unsupportedData3007Lỗi này cho biết định dạng dữ liệu không được SDK hỗ trợ.
fetchTimeoutError3101Lỗi này cho biết thao tác fetch đã hết thời gian chờ.
operationInProgress3201Chỉ trên iOS. Trong Unity là OperationInProgress. Một thao tác khác cùng loại vẫn đang chạy.
Được trả về bởi showStoreMessages khi một lệnh gọi trước đó vẫn đang hiển thị thông báo cửa hàng: xem Flutter, React Native, hoặc Unity. Hãy chờ nó hoàn tất rồi thử lại. Yêu cầu SDK 4.3.0 trở lên.
resolverFailure3202Chỉ trên iOS. Trong Unity là ResolverFailure. SDK không thể tìm thấy tài nguyên mà thao tác cần.
Được trả về bởi showStoreMessages khi không có window scene nào đang hoạt động ở foreground. Hãy gọi lại phương thức khi ứng dụng đang ở foreground. Yêu cầu SDK 4.3.0 trở lên.

Mã giao diện tùy chỉnh và mã plugin

LỗiMãGiải pháp
jsException4105Một ngoại lệ đã được ném từ JavaScript trong khi paywall hoặc onboarding được xây dựng trong builder đang chạy. Bật verbose logging để xem lỗi JavaScript bên dưới.
operationInterrupted9000Thao tác này bị hệ thống ngắt.
Hãy thử lại lệnh gọi.
emptyResult10001Flutter plugin nhận được kết quả trống từ SDK gốc.
Hãy thử lại lệnh gọi, sau đó xem phần Các vấn đề khác.
internalPluginError10002Đã xảy ra lỗi nội bộ trong Flutter plugin.
Xem phần Các vấn đề khác.

Các vấn đề khác

Nếu bạn vẫn chưa tìm được giải pháp, các bước tiếp theo có thể là:

  • Nâng cấp SDK lên phiên bản mới nhất: Chúng tôi luôn khuyến nghị nâng cấp lên phiên bản SDK mới nhất vì chúng ổn định hơn và bao gồm các bản sửa lỗi đã biết.
  • Liên hệ đội ngũ hỗ trợ hoặc nhận trợ giúp từ các nhà phát triển khác trong diễn đàn hỗ trợ.
  • Liên hệ đội ngũ hỗ trợ qua support@adapty.io hoặc qua chat: Nếu bạn chưa sẵn sàng nâng cấp SDK hoặc việc nâng cấp không giải quyết được vấn đề, hãy liên hệ đội ngũ hỗ trợ của chúng tôi. Lưu ý rằng vấn đề của bạn sẽ được giải quyết nhanh hơn nếu bạn bật ghi log chi tiết và chia sẻ log với đội ngũ. Bạn cũng có thể đính kèm các đoạn code liên quan.