title: "مرجع کدهای خطا" order: 11 description: "کدهای خطای نصب (پل بومی و PackageInstaller) و کدهای خطای بارگذاری، بررسی، پرداخت و API برای توسعه‌دهندگان"

مرجع کدهای خطا

این صفحه دو دسته کد را توضیح می‌دهد:

  1. کدهای خطای نصب (ERR_*) که ماژول نصب بومی بله گزارش می‌کند. پرتکرارترینِ آن‌ها برای برنامهٔ شما در داشبورد آمار کنسول (بخش «خطاهای پرتکرار نصب») دیده می‌شود.
  2. کدهای خطای 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 نظر توسط بررسی محتوا رد شد