title: "مرجع کدهای خطا" order: 11 description: "کدهای خطای نصب (پل بومی و PackageInstaller) و کدهای خطای بارگذاری، بررسی، پرداخت و API برای توسعهدهندگان"
مرجع کدهای خطا
این صفحه دو دسته کد را توضیح میدهد:
- کدهای خطای نصب (
ERR_*) که ماژول نصب بومی بله گزارش میکند. پرتکرارترینِ آنها برای برنامهٔ شما در داشبورد آمار کنسول (بخش «خطاهای پرتکرار نصب») دیده میشود. - کدهای خطای API (
UPPER_SNAKE) که در بدنهٔ خطای API کنسول، پرداخت و توزیع برمیگردند.
۱. کدهای خطای نصب: متن نمایش به کاربر
جدول زیر مستقیماً از INSTALL_ERROR_HELP در packages/contracts/src/errors.ts ساخته شده است؛ همین متنها را بلهاستور به کاربر نشان میدهد و از GET /v1/install-errors هم قابل دریافت است. ستون «اقدام» دکمهای است که رابط کاربری کنار پیام نشان میدهد.
| کد | عنوان | توضیح | راه رفع | اقدام |
|---|---|---|---|---|
ERR_NO_SPACE |
فضای کافی نیست | حافظهٔ گوشی برای دانلود و نصب این برنامه کافی نیست. | چند برنامه یا فایل بزرگ را پاک کنید و دوباره تلاش کنید. | free_space (آزادسازی فضا) |
ERR_NETWORK |
اتصال قطع شد | دانلود بهخاطر مشکل اینترنت متوقف شد. هرچه دانلود شده نگه داشته میشود. | اتصال اینترنت را بررسی کنید و «تلاش دوباره» را بزنید؛ دانلود از همانجا ادامه پیدا میکند. | retry (تلاش دوباره) |
ERR_HASH_MISMATCH |
فایل سالم نرسید | فایل دانلودشده با نسخهٔ تأییدشده یکی نبود و برای امنیت شما نصب نشد. | دوباره تلاش کنید. اگر تکرار شد، با پشتیبانی تماس بگیرید. | retry (تلاش دوباره) |
ERR_CERT_MISMATCH |
امضای برنامه معتبر نیست | امضای فایل با امضای ثبتشدهٔ سازنده یکی نبود و نصب متوقف شد. | این مورد گزارش شد. بعداً دوباره امتحان کنید. | contact_support (تماس با پشتیبانی) |
ERR_MANIFEST_SIGNATURE |
اطلاعات نصب معتبر نیست | اطلاعات نصب از سرور بلهاستور تأیید نشد. | تاریخ و ساعت گوشی را بررسی کنید و دوباره تلاش کنید. | retry (تلاش دوباره) |
ERR_MANIFEST_EXPIRED |
مهلت نصب تمام شد | اطلاعات نصب منقضی شده است. | دوباره «نصب» را بزنید. | retry (تلاش دوباره) |
ERR_INCOMPATIBLE |
با این گوشی سازگار نیست | این برنامه برای نسخهٔ اندروید یا پردازندهٔ گوشی شما ساخته نشده است. | برنامههای مشابه را در همین صفحه ببینید. | — |
ERR_DOWNGRADE |
نسخهٔ نصبشده جدیدتر است | نسخهٔ روی گوشی از نسخهٔ موجود در بلهاستور جدیدتر است و اندروید اجازهٔ نصب نسخهٔ قدیمیتر را نمیدهد. | نیازی به کاری نیست. | — |
ERR_CONFLICT |
از منبع دیگری نصب شده | نسخهٔ نصبشده با امضای دیگری ساخته شده و نمیتوان آن را بهروز کرد. | اگر میخواهید از بلهاستور نصب کنید، اول برنامهٔ فعلی را حذف کنید (اطلاعات آن پاک میشود). | open_settings (باز کردن تنظیمات) |
ERR_BLOCKED |
نصب مسدود شد | سیستم امنیتی گوشی (مثلاً Play Protect یا تنظیمات سازنده) نصب را متوقف کرد. | در تنظیمات، اجازهٔ «نصب برنامههای ناشناس» را برای بله فعال کنید و دوباره تلاش کنید. | open_settings (باز کردن تنظیمات) |
ERR_INSTALL_PERMISSION_DENIED |
اجازهٔ نصب لازم است | بله هنوز اجازهٔ نصب برنامه را ندارد. | در صفحهٔ بعد، «اجازه از این منبع» را روشن کنید. | open_settings (باز کردن تنظیمات) |
ERR_USER_CANCELLED |
نصب لغو شد | نصب را لغو کردید. | هر وقت خواستید دوباره «نصب» را بزنید. | retry (تلاش دوباره) |
ERR_NOT_ENTITLED |
اول باید خرید کنید | این برنامه پولی است و هنوز آن را نخریدهاید. | دکمهٔ خرید را بزنید. | — |
ERR_UNAUTHENTICATED |
وارد حساب نشدهاید | برای نصب باید با حساب بله وارد باشید. | صفحه را ببندید و دوباره باز کنید. | retry (تلاش دوباره) |
ERR_RATE_LIMITED |
کمی صبر کنید | درخواستهای نصب زیادی پشت سر هم ارسال شد. | چند ثانیه بعد دوباره تلاش کنید. | retry (تلاش دوباره) |
ERR_FORBIDDEN_ORIGIN |
صفحهٔ نامعتبر | این صفحه اجازهٔ نصب برنامه ندارد. | بلهاستور را از داخل بله باز کنید. | — |
ERR_NOT_IN_CATALOG |
در بلهاستور نیست | این برنامه در فهرست بلهاستور نیست. | — | — |
ERR_INSTALLER_STATUS_FAILURE_STORAGE |
فضای کافی نیست | اندروید بهخاطر کمبود فضا برنامه را نصب نکرد. | فضای گوشی را آزاد کنید و دوباره تلاش کنید. | free_space (آزادسازی فضا) |
ERR_INSTALLER_STATUS_FAILURE_CONFLICT |
تداخل با نسخهٔ نصبشده | برنامهای با همین نام اما امضای دیگر روی گوشی هست. | برنامهٔ فعلی را حذف کنید و دوباره نصب کنید. | open_settings (باز کردن تنظیمات) |
ERR_INSTALLER_STATUS_FAILURE_INCOMPATIBLE |
ناسازگار | اندروید این برنامه را با گوشی شما سازگار ندانست. | برنامههای مشابه را ببینید. | — |
ERR_INSTALLER_STATUS_FAILURE_BLOCKED |
نصب مسدود شد | نصب توسط سیستم یا مدیر دستگاه مسدود شد. | تنظیمات امنیتی گوشی را بررسی کنید. | open_settings (باز کردن تنظیمات) |
ERR_INSTALLER_STATUS_FAILURE_INVALID |
فایل نامعتبر | اندروید فایل نصب را نامعتبر تشخیص داد. | دوباره تلاش کنید؛ اگر تکرار شد گزارش دهید. | contact_support (تماس با پشتیبانی) |
ERR_INSTALLER_STATUS_FAILURE_ABORTED |
نصب متوقف شد | نصب نیمهکاره ماند. | دوباره تلاش کنید. | retry (تلاش دوباره) |
ERR_INSTALLER_STATUS_FAILURE_TIMEOUT |
زمان نصب تمام شد | نصب بیش از حد طول کشید. | دوباره تلاش کنید. | retry (تلاش دوباره) |
ERR_INSTALLER_STATUS_FAILURE |
نصب ناموفق بود | اندروید برنامه را نصب نکرد. | دوباره تلاش کنید؛ اگر تکرار شد با پشتیبانی تماس بگیرید. | contact_support (تماس با پشتیبانی) |
ERR_INTERNAL |
خطای غیرمنتظره | مشکلی پیش آمد. | دوباره تلاش کنید. | retry (تلاش دوباره) |
ERR_UNKNOWN_JOB |
کار نصب پیدا نشد | این نصب دیگر در صف نیست (احتمالاً قبلاً تمام یا لغو شده است). | صفحه را تازه کنید. | — |
ERR_UNKNOWN_JOBدرINSTALL_ERROR_HELPنیست؛ متن ردیف آخر پیشنهادی است. این کد فقط پاسخ فراخوانیcancel(jobId)با شناسهٔ ناشناخته است و هیچوقت در رویداد پیشرفت نصب ظاهر نمیشود. اگر کدی در این جدول نبود، رابط کاربری متنERR_INTERNALرا نشان میدهد.
۲. کدهای خطای نصب: توضیح فنی برای توسعهدهنده
| کد | کجا رخ میدهد | علت فنی | آیا کاری از توسعهدهنده برمیآید؟ |
|---|---|---|---|
ERR_NO_SPACE |
پیش از دانلود / حین دانلود | فضای خالی دستگاه کمتر از حجم فایلها | حجم APK را کم کنید؛ از split استفاده کنید تا هر دستگاه فقط فایلهای لازم را بگیرد. |
ERR_NETWORK |
دانلود | قطع شبکه یا شکست همهٔ نشانیهای CDN؛ دانلود با HTTP Range ادامهپذیر است | خیر. |
ERR_HASH_MISMATCH |
بررسی پس از دانلود | SHA-256 فایل دریافتی با manifest امضاشده یکی نیست | خیر؛ فایلها پاک و رخداد امنیتی ثبت میشود. |
ERR_CERT_MISMATCH |
بررسی پس از دانلود | گواهی امضای APK در manifest نیست، یا امضاکنندهٔ نسخهٔ نصبشده با گواهیهای برنامه نمیخواند | اگر کلید را عوض کردهاید، فقط از چرخش کلید v3/v3.1 استفاده کنید. |
ERR_MANIFEST_SIGNATURE |
دریافت manifest | امضای manifest نامعتبر یا kid ناشناخته |
خیر (معمولاً ساعت دستگاه یا شبکهٔ دستکاریشده). |
ERR_MANIFEST_EXPIRED |
دریافت manifest | manifest منقضی شده (اعتبار پیشفرض ۱۵ دقیقه، قابل تنظیم) | خیر. |
ERR_INCOMPATIBLE |
دریافت manifest | minSdk بالاتر از اندروید دستگاه، یا ABI مناسب وجود ندارد (سرور 409 INCOMPATIBLE_DEVICE) |
بله: minSdk را بازبینی کنید و برای همهٔ ABIهای هدف (بهویژه arm64-v8a) کتابخانهٔ بومی یا split بگذارید. |
ERR_DOWNGRADE |
پیش از نصب | versionCode نصبشده (مثلاً از فروشگاه دیگر) از نسخهٔ بلهاستور بیشتر است | بله: همان نسخهٔ جدیدتر را در بلهاستور هم منتشر کنید. |
ERR_CONFLICT |
پیش از نصب | برنامه با کلید امضای دیگری نصب شده است؛ اندروید بهروزرسانی را اجازه نمیدهد | بله: در همهٔ فروشگاهها با یک کلید امضا کنید. |
ERR_BLOCKED |
نصب | سیاست دستگاه (Play Protect، تنظیمات سازنده یا مدیر دستگاه) نصب را مسدود کرد | معمولاً خیر. |
ERR_INSTALL_PERMISSION_DENIED |
پیش از نصب | مجوز «نصب برنامههای ناشناس» برای بله داده نشده است | خیر. |
ERR_USER_CANCELLED |
هر مرحله | کاربر نصب را لغو کرد یا دیالوگ تأیید سیستم را رد کرد | خیر. |
ERR_NOT_ENTITLED |
دریافت manifest | برنامهٔ پولی خریده نشده (سرور 402 NOT_ENTITLED) |
خیر. |
ERR_UNAUTHENTICATED |
دریافت manifest | نشست کاربر نامعتبر یا منقضی | خیر. |
ERR_RATE_LIMITED |
فراخوانی install |
بیش از ۱۰ درخواست نصب در دقیقه از یک صفحه | خیر. |
ERR_FORBIDDEN_ORIGIN |
هر فراخوانی پل | صفحهٔ فراخواننده در فهرست مجاز نیست | خیر. |
ERR_NOT_IN_CATALOG |
getInstalledPackages / open / openUninstall |
بسته در فهرست مجاز کاتالوگ ماژول نیست | خیر. |
ERR_UNKNOWN_JOB |
cancel |
شناسهٔ کار نصب ناشناخته | خیر. |
ERR_INSTALLER_STATUS_* |
نصب | وضعیت بازگشتی PackageInstaller (جدول بعد) |
برای INVALID و INCOMPATIBLE: APK و splitها را با adb install-multiple آزمایش کنید. |
ERR_INTERNAL |
هر جا | خطای پیشبینینشده، JSON نامعتبر یا timeout پاسخ پل | خیر. |
۳. نگاشت وضعیت PackageInstaller به کد پل
ماژول نصب، نتیجهٔ PackageInstaller.Session.commit() را اینطور ترجمه میکند:
PackageInstaller |
نتیجه در پل | توضیح |
|---|---|---|
STATUS_SUCCESS |
حالت INSTALLED |
نصب موفق |
STATUS_PENDING_USER_ACTION |
حالت PENDING_USER_ACTION |
intent تأیید سیستم اجرا میشود و به فروشگاه خبر داده میشود؛ پس از تأیید، نتیجهٔ نهایی میرسد |
STATUS_FAILURE |
ERR_INSTALLER_STATUS_FAILURE |
شکست عمومی |
STATUS_FAILURE_ABORTED |
ERR_INSTALLER_STATUS_FAILURE_ABORTED، یا ERR_USER_CANCELLED وقتی کاربر دیالوگ تأیید را رد کرده است |
نصب نیمهکاره ماند |
STATUS_FAILURE_BLOCKED |
ERR_INSTALLER_STATUS_FAILURE_BLOCKED |
مسدود توسط سیستم یا مدیر دستگاه |
STATUS_FAILURE_CONFLICT |
ERR_INSTALLER_STATUS_FAILURE_CONFLICT |
تداخل با بستهٔ موجود (مثلاً امضای متفاوت) |
STATUS_FAILURE_INCOMPATIBLE |
ERR_INSTALLER_STATUS_FAILURE_INCOMPATIBLE |
ناسازگار با دستگاه (ABI، SDK، ویژگیها) |
STATUS_FAILURE_INVALID |
ERR_INSTALLER_STATUS_FAILURE_INVALID |
فایل یا مجموعهٔ split نامعتبر |
STATUS_FAILURE_STORAGE |
ERR_INSTALLER_STATUS_FAILURE_STORAGE |
کمبود فضا هنگام نصب |
STATUS_FAILURE_TIMEOUT |
ERR_INSTALLER_STATUS_FAILURE_TIMEOUT |
پایان مهلت نصب (مثلاً طول کشیدن بررسی verifier سیستم) |
کدهای ERR_CERT_MISMATCH، ERR_CONFLICT، ERR_DOWNGRADE و ERR_INCOMPATIBLE معمولاً پیش از ساختن نشست نصب، در بررسیهای خود ماژول (manifest امضاشده و اطلاعات بستهٔ نصبشده) تشخیص داده میشوند؛ کدهای ERR_INSTALLER_STATUS_* همان چیزی است که خود اندروید برگردانده است.
<a id="console-errors"></a>
۴. کدهای خطای API
بدنهٔ همهٔ خطاها:
{ "error": { "code": "VERSION_CODE_NOT_INCREASING", "message": "<متن فارسی>", "details": { } } }
message فارسی و قابل نمایش است؛ برای منطق برنامه به code تکیه کنید.
کدهای عمومی
| کد | HTTP | معنی |
|---|---|---|
UNAUTHORIZED |
401 | توکن ندارید یا نامعتبر/منقضی است |
FORBIDDEN |
403 | دسترسی کافی ندارید |
NOT_FOUND |
404 | منبع پیدا نشد |
VALIDATION_FAILED |
400 / 422 | ورودی نامعتبر؛ خطای هر فیلد در details.fields |
CONFLICT |
409 | تعارض با وضعیت فعلی |
RATE_LIMITED |
429 | درخواست بیش از حد مجاز |
FEATURE_DISABLED |
503 | قابلیت موقتاً غیرفعال است |
UPSTREAM_UNAVAILABLE |
503 | سرویس وابسته در دسترس نیست |
INTERNAL |
500 | خطای داخلی |
ورود و حساب
| کد | معنی | راه رفع |
|---|---|---|
INVALID_BALE_TOKEN |
توکن ورود بله نامعتبر است | دوباره از بله وارد شوید. |
OTP_INVALID |
کد یکبارمصرف اشتباه است | کد را دوباره وارد کنید. |
OTP_EXPIRED |
کد یکبارمصرف منقضی شده | کد تازه بخواهید. |
TOTP_REQUIRED |
ورود دومرحلهای لازم است (نقشهای owner، admin، finance) |
کد برنامهٔ احراز هویت را هم بفرستید یا TOTP را راهاندازی کنید. |
TOTP_INVALID |
کد دومرحلهای اشتباه است | ساعت گوشی را بررسی و دوباره تلاش کنید. |
SESSION_EXPIRED |
نشست منقضی شده | با refresh token نشست را تازه کنید یا دوباره وارد شوید. |
سازمان، بارگذاری و انتشار (کنسول)
| کد | معنی | راه رفع |
|---|---|---|
ORG_NOT_VERIFIED |
احراز هویت سازمان کامل نشده است | کد ملی / شناسهٔ ملی و موبایل را تأیید کنید. |
AGREEMENT_NOT_ACCEPTED |
نسخهٔ جاری قرارداد توزیع پذیرفته نشده | مالک سازمان قرارداد جدید را بپذیرد. |
ORG_SUSPENDED |
سازمان تعلیق یا محدود شده است | با پشتیبانی بلهاستور تماس بگیرید. |
ROLE_REQUIRED |
نقش شما برای این کار کافی نیست | از owner یا admin بخواهید نقش لازم را بدهد. |
UPLOAD_INCOMPLETE |
همهٔ قطعههای فایل نرسیدهاند | با GET /console/v1/uploads/{uploadId} قطعههای جاافتاده را ببینید و بفرستید. |
UPLOAD_TOO_LARGE |
حجم فایل از سقف بیشتر است (پیشفرض ۱ گیگابایت، قابل تنظیم) | حجم را کم کنید یا از split استفاده کنید. |
APK_INVALID |
فایل APK سالم یا قابل خواندن نیست (یا AAB است) | APK امضاشدهٔ انتشار را بارگذاری کنید؛ AAB پذیرفته نمیشود. |
PACKAGE_TAKEN |
این نام بسته قبلاً توسط سازمان دیگری ثبت شده | اگر مالک واقعی هستید، ادعای مالکیت (POST /console/v1/disputes) ثبت کنید. |
PACKAGE_MISMATCH |
نام بستهٔ فایل با برنامه یا با سایر فایلهای همین نسخه یکی نیست | همهٔ فایلهای نسخه (base و splitها) باید نام بستهٔ برنامه را داشته باشند. |
VERSION_CODE_NOT_INCREASING |
versionCode بزرگتر از آخرین نسخهٔ منتشرشده نیست | versionCode را افزایش دهید. |
CERT_MISMATCH |
گواهی امضا با گواهی ثبتشدهٔ برنامه یکی نیست و زنجیرهٔ چرخش معتبری هم ندارد | با کلید اصلی امضا کنید یا از چرخش کلید v3/v3.1 استفاده کنید. |
TARGET_SDK_TOO_LOW |
targetSdk پایینتر از کف سیاست است | targetSdk را بالا ببرید (سیاستها). |
MISSING_ARM64 |
کد بومی دارید ولی arm64-v8a ندارید |
کتابخانههای ۶۴بیتی را اضافه کنید. |
DEBUGGABLE_BUILD |
android:debuggable="true" است |
بیلد release بسازید. |
OWNERSHIP_NOT_VERIFIED |
مالکیت بسته هنوز اثبات نشده | اثبات مالکیت را کامل کنید. |
OWNERSHIP_TOKEN_MISMATCH |
توکن داخل APK اثبات با توکن فعلی یکی نیست | توکن را دوباره کپی و APK را بسازید. |
OWNERSHIP_CERT_MISMATCH |
APK اثبات با کلید برنامه امضا نشده | با همان keystore/alias امضا کنید. |
OWNERSHIP_PACKAGE_MISMATCH |
نام بستهٔ APK اثبات با برنامه یکی نیست | نام بسته را دقیق وارد کنید. |
OWNERSHIP_TOKEN_EXPIRED |
توکن اثبات (۷ روزه) منقضی شده | توکن تازه بگیرید. |
LISTING_INCOMPLETE |
صفحهٔ فروشگاه فارسی کامل نیست | فیلدهای validation صفحهٔ فروشگاه را کامل کنید. |
INVALID_STATE_TRANSITION |
این کار در وضعیت فعلی مجاز نیست (مثلاً انتشار نسخهای که تأیید نشده) | وضعیت نسخه را بررسی کنید. |
پرداخت
| کد | معنی |
|---|---|
BILLING_DISABLED |
پرداخت موقتاً غیرفعال است (نصب برنامههای رایگان ادامه دارد) |
NOT_ENTITLED |
کاربر این برنامهٔ پولی را نخریده است |
ALREADY_OWNED |
کاربر این محصول را قبلاً دارد |
INSUFFICIENT_FUNDS |
موجودی کافی نیست |
PAYMENT_FAILED |
پرداخت ناموفق بود |
SKU_NOT_FOUND |
محصول وجود ندارد یا غیرفعال است |
PURCHASE_NOT_FOUND |
خرید یافت نشد |
ALREADY_CONSUMED |
خرید قبلاً مصرف شده است |
REFUND_WINDOW_CLOSED |
مهلت درخواست بازپرداخت تمام شده است (مدت مهلت در حال نهاییشدن است) |
REFUND_EXCEEDS_AMOUNT |
مبلغ بازپرداخت بیش از مبلغ باقیماندهٔ سفارش است |
PAYOUTS_FROZEN |
تسویهها موقتاً متوقف شدهاند (مثلاً بهخاطر بررسی مالی یا تعلیق حساب) |
FOUR_EYES_SAME_ACTOR |
(داخلی کارکنان) تأیید دوم باید توسط فرد دیگری انجام شود |
توزیع و نصب
| کد | HTTP | معنی |
|---|---|---|
APP_NOT_AVAILABLE |
— | برنامه یا نسخه در دسترس نیست |
INCOMPATIBLE_DEVICE |
409 | برنامه با این دستگاه سازگار نیست (minSdk یا ABI) |
APP_PULLED |
410 | برنامه یا نسخه از دسترس خارج شده (حذف فوری یا عدم انتشار) |
NOT_ENTITLED |
402 | برنامهٔ پولی خریده نشده |
نظرات کاربران
| کد | معنی |
|---|---|
NOT_VERIFIED_INSTALL |
فقط کاربرانی که برنامه را از بلهاستور نصب کردهاند میتوانند نظر بدهند |
REVIEW_REJECTED_BY_MODERATION |
نظر توسط بررسی محتوا رد شد |