Обработка ошибок в Flutter SDK
Каждая ошибка, возвращаемая SDK, имеет тип AdaptyErrorCode. Пример:
Включите подробные логи перед отладкой. Большинство AdaptyErrors оборачивают исходную ошибку StoreKit, Play Billing, сети или бэкенда. При включённых подробных логах (await Adapty().setLogLevel(AdaptyLogLevel.verbose) — см. Логирование) эта ошибка выводится в консоль, что обычно сразу указывает на причину.
Если эти решения не помогли, см. раздел Другие проблемы, где описаны шаги, которые стоит предпринять перед обращением в поддержку — это поможет нам помочь вам быстрее.
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 |
Убедитесь, что нужные предложения настроены в AppStore Connect, и передайте корректный идентификатор предложения. |
| invalidSignature | 12 | Этот код ошибки указывает, что подпись в скидке на оплату недействительна. |
| missingOfferParams | 13 | Этот код ошибки указывает, что в скидке на оплату отсутствуют параметры. |
| invalidOfferPrice | 14 | Этот код ошибки указывает, что цена, указанная вами в App Store Connect, больше не является действительной. Предложения всегда должны представлять сниженную цену. |
Кастомные коды ошибок Android
| Ошибка | Код | Решение |
|---|---|---|
| adaptyNotInitialized | 20 | Необходимо правильно настроить Adapty SDK с помощью метода Adapty.activate. Узнайте, как это сделать для Flutter. |
| productNotFound | 22 | Эта ошибка означает, что запрошенный для покупки продукт недоступен в сторе. |
| invalidJson | 23 | JSON пейвола недействителен. Исправьте его в дашборде Adapty. Подробнее о том, как это сделать, читайте в разделе Настройка пейвола с помощью Remote Config. |
| currentSubscriptionToUpdateNotFoundInHistory | 24 | Исходная подписка, которую необходимо продлить, не найдена. |
| pendingPurchase | 25 | Эта ошибка означает, что статус покупки — ожидающий, а не выполненный. Подробнее см. страницу Обработка ожидающих транзакций в документации Android Developer. |
| billingServiceTimeout | 97 | Эта ошибка означает, что запрос достиг максимального тайм-аута до того, как Google Play успел ответить. Причиной может быть, например, задержка выполнения действия, запрошенного вызовом Play Billing Library. |
| featureNotSupported | 98 | Запрошенная функция не поддерживается Play Store на данном устройстве. |
| billingServiceDisconnected | 99 | Эта фатальная ошибка означает, что соединение клиентского приложения с сервисом Google Play Store через BillingClient было разорвано. |
| billingServiceUnavailable | 102 | Эта временная ошибка означает, что сервис Google Play Billing в данный момент недоступен. В большинстве случаев это свидетельствует о проблеме с сетевым соединением между клиентским устройством и сервисами Google Play Billing. |
| 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, хотя они там и перечислены. Иногда вместе с ней появляется предупреждение Если вы сталкиваетесь с этой ошибкой, следуйте шагам в разделе Fix for Code-1000 |
| productRequestFailed | 1002 | В данный момент не удаётся загрузить доступные продукты. |
| cantMakePayments | 1003 | Встроенные покупки запрещены на этом устройстве. См. гайд по устранению проблемы. |
| noPurchasesToRestore | 1004 | Устарело в Adapty Flutter SDK 4.0.4: restorePurchases() больше не возвращает эту ошибку. Если нечего восстанавливать, метод завершается успешно с текущим профилем — проверьте в нём статус уровня доступа. В более ранних версиях SDK эта ошибка означает, что Google Play не нашёл покупку для восстановления. |
| cantReadReceipt | 1005 | На устройстве нет действительного чека. Это может быть проблемой при тестировании в песочнице. В песочнице действительный файл чека появляется только после реальной покупки, поэтому сначала совершите её. При тестировании в песочнице также убедитесь, что на устройстве выполнен вход под действительным аккаунтом Apple sandbox. |
| productPurchaseFailed | 1006 | Не удалось совершить покупку продукта. Эта ошибка оборачивает базовую ошибку StoreKit — прочитайте вложенную ошибку (или включите подробные логи, чтобы увидеть её в консоли) для выяснения реальной причины. Вложенная ошибка, как правило, является одним из кодов StoreKit 0–14 из таблицы выше — чаще всего paymentCancelled, paymentInvalid, paymentNotAllowed или invalidOfferPrice. Если определить конкретную причину не удаётся, попробуйте создать новый профиль песочницы; если проблема сохраняется, обратитесь в поддержку Apple. |
| refreshReceiptFailed | 1010 | Эта ошибка означает, что чек не был получен. Применимо только к StoreKit 1. |
| receiveRestoredTransactionsFailed | 1011 | Не удалось восстановить покупки. |
| billingPlanUnavailable | 1060 | Только iOS. Продукт не предлагает запрошенный тарифный план на этом устройстве или в этом регионе магазина. Для плана с 12-месячным обязательством требуется iOS 26.4 или выше и приложение, собранное с Xcode 26.5 или выше. Требуется SDK 4.3.0 или выше. |
Пользовательские сетевые коды
| Ошибка | Код | Решение |
|---|---|---|
| notActivated | 2002 | SDK Adapty не активирован. Чаще всего возникает, когда экран-заставка или ранний UI-хук вызывает методы Adapty до того, как Adapty().activate завершится. Симптом непостоянный и может не воспроизводиться в эмуляторе из-за различий в тайминге на реальном устройстве. Добавьте await к Future activate перед любым другим вызовом SDK. Полная последовательность описана в разделе Порядок вызовов во Flutter SDK. |
| badRequest | 2003 | Некорректный запрос. Убедитесь, что вы выполнили все шаги, необходимые для интеграции с App Store. |
| serverError | 2004 | Ошибка сервера. Повторите попытку через некоторое время. Если проблема не устранена, обратитесь в службу поддержки Adapty. |
| networkFailed | 2005 | Ошибка указывает на проблемы с сетевым подключением на устройстве пользователя. Попробуйте отключить VPN или переключиться с мобильной сети на Wi-Fi или наоборот. |
| decodingFailed | 2006 | Ошибка декодирования ответа. Проверьте код и убедитесь, что передаваемые параметры корректны. Например, эта ошибка может указывать на использование недействительного API-ключа. |
| encodingFailed | 2009 | Ошибка кодирования запроса. |
| analyticsDisabled | 3000 | Обработка аналитических событий недоступна, так как вы отключили её. |
| wrongParam | 3001 | Один или несколько параметров указаны неверно. Если вы используете Paywall Builder и пейвол не отображается из-за этой ошибки, включите Show on device в настройках Paywall Builder. Ещё одна возможная причина — версия локального файла резервного пейвола не совпадает с версией SDK. Скачайте новый файл в дашборде. |
| activateOnceError | 3005 | Метод .activate нельзя вызывать более одного раза. |
| profileWasChanged | 3006 | Профиль пользователя был изменён во время операции. Это происходит, когда метод вызывается в то время, пока Adapty().identify ещё выполняется — выполняемый вызов попадает на профиль, который вот-вот будет заменён, и SDK отклоняет его. Всегда добавляйте await к identify перед любым вызовом, связанным с действиями пользователя. См. Порядок вызовов во Flutter SDK. |
| unsupportedData | 3007 | Формат данных не поддерживается SDK. |
| fetchTimeoutError | 3101 | Превышено время ожидания операции получения данных. |
| operationInProgress | 3201 | Только iOS. В Unity — OperationInProgress. Другая операция того же типа ещё выполняется. Возвращается методом showStoreMessages, если предыдущий вызов всё ещё показывает сообщения стора: см. Flutter, React Native или Unity. Дождитесь завершения и повторите попытку. Требуется SDK версии 4.3.0 или выше. |
| resolverFailure | 3202 | Только iOS. В Unity — ResolverFailure. SDK не удалось найти ресурс, необходимый для операции. Возвращается методом showStoreMessages, если отсутствует активная оконная сцена на переднем плане. Вызовите метод повторно, когда приложение находится на переднем плане. Требуется SDK версии 4.3.0 или выше. |
Пользовательский UI и коды плагинов
| Ошибка | Код | Решение |
|---|---|---|
| jsException | 4105 | Исключение было выброшено из JavaScript во время работы пейвола или онбординга, созданного в билдере. Включите подробное логирование, чтобы увидеть underlying JavaScript-ошибку. |
| operationInterrupted | 9000 | Операция была прервана системой. Повторите вызов. |
| emptyResult | 10001 | Flutter-плагин получил пустой результат от нативного SDK. Повторите вызов, затем обратитесь к разделу Другие проблемы. |
| internalPluginError | 10002 | Во Flutter-плагине произошла внутренняя ошибка. Обратитесь к разделу Другие проблемы. |
Другие проблемы
Если вы ещё не нашли решение, попробуйте следующее:
- Обновите SDK до последней версии: мы всегда рекомендуем переходить на актуальные версии SDK — они стабильнее и содержат исправления известных проблем.
- Обратитесь в поддержку или получите помощь от других разработчиков на форуме.
- Напишите в поддержку на support@adapty.io или через чат: если вы не готовы обновлять SDK или это не помогло, обратитесь в нашу службу поддержки. Обратите внимание: проблема решится быстрее, если вы включите подробное логирование и поделитесь логами с командой. Также можно прикрепить соответствующие фрагменты кода.