Adapty SDK có lớp bọc riêng cho tất cả các loại lỗi, gọi là AdaptyError. Về cơ bản, mọi lỗi được SDK trả về đều là AdaptyError. Nó có hai thuộc tính hữu ích: originalError và adaptyErrorCode, được mô tả bên dưới.

originalError chứa lỗi gốc trong trường hợp bạn cần làm việc trực tiếp với nó. Có thể là SKError, NSError hoặc Error thông thường trong Swift. Thuộc tính này là tùy chọn vì một số lỗi có thể được SDK tạo ra trực tiếp — ví dụ như dữ liệu không nhất quán hoặc thiếu dữ liệu — và sẽ không có lỗi gốc mà lớp bọc ban đầu được xây dựng xung quanh.

adaptyErrorCode có thể được dùng để xử lý các vấn đề phổ biến, như:

• thông tin xác thực không hợp lệ
• lỗi mạng
• thanh toán bị hủy
• vấn đề thanh toán
• biên lai không hợp lệ
• và nhiều hơn nữa

Việc kiểm tra lỗi theo mã cụ thể và phản hồi phù hợp khá đơn giản.

do {
    let info = try await Adapty.makePurchase(product: product)
} catch {
    if error.adaptyErrorCode == .paymentCancelled {
        // purchase was cancelled
        // you can offer discount to your user or remind them later
    }
}

Lỗi StoreKit

Lỗi	Mã	Giải pháp
unknown	0	Mã 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.
clientInvalid	1	Mã lỗi này cho biết client không được phép thực hiện hành động đã cố gắng.
paymentCancelled	2	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 kinh doanh, bạn có thể đề xuất giảm giá cho người dùng hoặc nhắc nhở họ sau.
paymentInvalid	3	Lỗ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.
paymentNotAllowed	4	Mã lỗi này cho biết người dùng không được phép ủy quyền thanh toán.
storeProductNotAvailable	5	Mã 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. Hãy thử cài đặt lại ứng dụng.
cloudServicePermissionDenied	6	Mã 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.
cloudServiceNetworkConnectionFailed	7	Mã lỗi này cho biết thiết bị không thể kết nối mạng.
cloudServiceRevoked	8	Mã 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.
privacyAcknowledgementRequired	9	Mã 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.
unauthorizedRequestData	10	Mã 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.
invalidOfferIdentifier	11	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 đó trong 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 offer identifier hợp lệ.
invalidSignature	12	Mã lỗi này cho biết chữ ký trong payment discount không hợp lệ.
missingOfferParams	13	Mã lỗi này cho biết các tham số bị thiếu trong payment discount.
invalidOfferPrice	14	Mã lỗi này cho biết 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á đã giảm.
noProductIDsFound	1000	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 trong App Store, dù chúng được liệt kê ở đó. Lỗi này đôi khi xuất hiện kèm 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ếu gặp lỗi này, hãy làm theo các bước trong phần Fix for Code-1000 noProductIDsFound error.
productRequestFailed	1002	Không thể lấy danh sách sản phẩm khả dụng tại thời điểm này.
cantMakePayments	1003	In-app purchase không được cho phép trên thiết bị này. Xem hướng dẫn khắc phục sự cố.
cantReadReceipt	1005	Không có biên lai hợp lệ trên thiết bị. Đây có thể là vấn đề khi kiểm thử sandbox. Trong sandbox, bạn sẽ không có file biên lai 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 thực hiện một lần trước khi truy cập. Khi kiểm thử sandbox, cũng đảm bảo bạn đã đăng nhập trên thiết bị bằng tài khoản Apple sandbox hợp lệ.
productPurchaseFailed	1006	Mua sản phẩm thất bại. Lỗi này bọc một lỗi StoreKit bên dưới — đọc originalError (hoặc bật verbose logs để xem trong console) để biết nguyên nhân thực sự. Lỗi bọc 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 không xác định được nguyên nhân cụ thể, hãy thử tạo sandbox profile mới; nếu vẫn thất bại, liên hệ Apple support.
refreshReceiptFailed	1010	Thao tác làm mới biên lai thất bại.
fetchSubscriptionStatusFailed	1020	Không thể lấy trạng thái gói đăng ký từ App Store.
unknownTransactionId	1030	Mã giao dịch không xác định.
paymentPendingError	1050	Thanh toán đang ở trạng thái chờ xử lý.

Lỗi mạng

Lỗi	Mã	Giải pháp
notActivated	2002	Adapty SDK chưa được kích hoạt. Thường gặp nhất khi màn hình splash hoặc một hook UI sớm gọi các phương thức Adapty trước khi Adapty.activate hoàn thành. Triệu chứng có thể không ổn định và không tái hiện trên simulator vì thời gian thực thi trên thiết bị thật khác nhau. Hãy await completion handler hoặc async result của activate trước khi gọi bất kỳ SDK call nào khác. Xem Thứ tự gọi trong iOS SDK để biết đầy đủ trình tự.
badRequest	2003	Bad request. Đả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.
serverError	2004	Lỗi server. Thử lại sau một thời gian. Nếu vẫn chưa giải quyết được, hãy liên hệ đội hỗ trợ Adapty.
networkFailed	2005	Lỗ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 từ mạng di động sang WiFi hoặc ngược lại.
decodingFailed	2006	Lỗi này cho biết việc giải mã phản hồi thất bại. Xem lại code của bạn và đảm bảo các tham số bạn gửi là hợp lệ. Ví dụ, lỗi này có thể cho biết bạn đang dùng API key không hợp lệ.
encodingFailed	2009	Lỗi này cho biết việc mã hóa yêu cầu thất bại.

Lỗi chung

Lỗi	Mã	Giải pháp
analyticsDisabled	3000	Chú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.
wrongParam	3001	Lỗ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 và không thể hiển thị paywall vì lỗi này, hãy bật Show on device trong paywall builder. Nguyên nhân khác có thể là phiên bản file fallback cục bộ không khớp với phiên bản SDK. Tải file mới trong dashboard.
activateOnceError	3005	Không thể gọi phương thức .activate nhiều hơn một lần.
profileWasChanged	3006	Hồ 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 kết thúc trên một hồ sơ sắp bị thay thế, và SDK từ chối nó. Luôn await identify (hoặc dùng completion handler của nó) trước bất kỳ lệnh gọi nào liên quan đến hành động người dùng. Xem Thứ tự gọi trong iOS SDK.
unsupportedData	3007	Lỗi này cho biết định dạng dữ liệu không được SDK hỗ trợ.
unidentifiedUserLogout	3020	Không thể gọi phương thức logout cho người dùng chưa được xác định.
fetchTimeoutError	3101	Lỗi này cho biết thao tác fetch đã hết thời gian chờ.
operationInterrupted	9000	Thao tác này đã bị hệ thống ngắt.

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 các 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 hỗ trợ hoặc nhờ giúp đỡ từ các lập trình viên khác trong diễn đàn hỗ trợ.
• Liên hệ đội 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úp ích, hãy liên hệ đội 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 verbose logging và chia sẻ logs với đội ngũ. Bạn cũng có thể đính kèm các đoạn code liên quan.