کدهای خطا و وضعیت‌های HTTP

هر خطا در کنار وضعیت HTTP یک کد پایدار و ماشین‌خوان برمی‌گرداند. بر اساس کد شرط بگذارید، نه بر اساس متن پیام: پیام‌ها برای انسان نوشته شده‌اند و ممکن است بازنویسی شوند، در حالی که کدها بخشی از قرارداد هستند.

همه 42 کدی که API نمایندگی می‌تواند برگرداند، بر اساس نوع مشکل دسته‌بندی شده‌اند. هر مورد، وضعیت HTTP که با آن می‌آید و تغییری که آن را حل می‌کند مشخص می‌کند.

احراز هویت (401)

کدHTTPیعنی چهچگونه رفع می‌شود
MISSING_API_KEY401کلید API الزامی استهدر Authorization ارسال نشده یا قالب آن درست نیست.کلید دسترسی را در هدر هر درخواست بفرستید؛ قالب درست چنین است: Authorization: Bearer <keyId>.<secret>action: FIX_INPUT · retryable: false · retry_after: null
INVALID_API_KEY401کلید API نامعتبر استکلید API ارسال‌شده با هیچ کلید فعالی در سیستم مطابقت ندارد.درستی شناسه کلید و secret خود را بررسی کنید. در صورت نیاز، کلید را از پنل API Access دوباره بسازید.action: FIX_INPUT · retryable: false · retry_after: null

سطح دسترسی (403)

کدHTTPیعنی چهچگونه رفع می‌شود
ACCOUNT_DISABLED403حساب غیرفعال استاین خطا دیگر برگردانده نمی‌شود. برای حسابی که نمی‌تواند سفارش ثبت کند، پاسخ ACCOUNT_FROZEN (HTTP 403) است.به‌جای آن، خطای ACCOUNT_FROZEN را مدیریت کنید.دیگر برگردانده نمی‌شود؛ جایگزین: ACCOUNT_FROZEN
ACCOUNT_FROZEN403حساب مسدود شده استحساب شما به‌طور موقت مسدود شده است. معمولاً دلیل آن فعالیت مشکوک است.برای رفع مسدودی حساب با پشتیبانی تماس بگیرید.action: CONTACT_SUPPORT · retryable: false · retry_after: null
IP_NOT_ALLOWED403آدرس IP در فهرست مجاز نیستدرخواست از آدرس IP‌ای ارسال شده که در فهرست مجاز کلید API شما نیست.آدرس IP سرور خود را در پنل API Access به فهرست مجاز اضافه کنید یا محدودیت IP را بردارید.action: FIX_INPUT · retryable: false · retry_after: null

اعتبارسنجی درخواست (400)

کدHTTPیعنی چهچگونه رفع می‌شود
MISSING_REQUIRED_FIELD400یک فیلد الزامی ارسال نشده استیکی از فیلدهای الزامی در بدنه درخواست نیست. در فیلدهای مربوط به بازیکن، نام فیلد جاافتاده در details.field آمده است.مستندات این اندپوینت و برای فیلدهای بازیکن، GET /catalog/category/:categoryId/requirements را بررسی کنید و همه فیلدهای الزامی را بفرستید.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PARAMETER_FORMAT400قالب یکی از پارامترها نامعتبر استیکی از فیلدهای الزامی قالب اشتباهی دارد (مثلاً متن در یک فیلد عددی). نام فیلد در details.field مشخص شده است.الزامات دسته‌بندی را دوباره بخوانید و فیلد را با قالبی بفرستید که data_type و قواعد اعتبارسنجی آن انتظار دارند.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PARAMETER_VALUE400مقدار یکی از پارامترها نامعتبر استمقدار یکی از فیلدهای الزامی خارج از محدوده مجاز است (کمتر از حداقل، بیشتر از حداکثر یا جزو select_options نیست). فیلد مربوط در details.field آمده است.برای این فیلد مقداری بفرستید که الزامات دسته‌بندی مجاز می‌دانند.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PARAMETER_LENGTH400طول یکی از پارامترها نامعتبر استطول یکی از فیلدهای مورد نیاز کوتاه‌تر یا بلندتر از حد مجاز است. نام این فیلد در details.field آمده است.مقدار min_length / max_length را در الزامات دسته‌بندی بررسی کنید.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_UUID_FORMAT400قالب UUID نامعتبر استمقدار ارسال‌شده برای order_id یک UUID معتبر نیست.می‌توانید از هر قالب معتبر UUID استفاده کنید، مثل نسخه‌های v1، v4، v7 و نسخه‌های دیگر. ساختار شناسه باید دقیقاً این‌گونه باشد: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_QUANTITY400تعداد نامعتبر استتعداد باید یک عدد صحیح مثبت باشد.تعداد را به‌صورت عدد صحیح و برابر یا بیشتر از ۱ ارسال کنید.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_CATEGORY_ID400شناسه دسته‌بندی نامعتبر استcategoryId ارسال‌شده یک عدد معتبر نیست.برای پیدا کردن شناسه‌های معتبر دسته‌بندی، از ابزار Catalog Explorer کمک بگیرید یا درخواست GET /catalog/categories را بفرستید.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_BIG_CATEGORY_ID400شناسه دسته‌بندی اصلی نامعتبر استbigCategoryId ارسال‌شده عدد معتبری نیست.شناسه‌های معتبر دسته‌بندی اصلی را در ابزار Catalog Explorer پیدا کنید یا فهرست آن‌ها را با درخواست GET /catalog/big-categories بگیرید.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_ITEM_ID400شناسه آیتم نامعتبر استشناسه آیتم ارسال‌شده معتبر نیست.فهرست شناسه‌های معتبر آیتم‌ها را می‌توانید در ابزار Catalog Explorer ببینید یا آن را با درخواست GET /catalog/subcategories دریافت کنید.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_SUBCATEGORY400زیردسته نامعتبر استزیردسته‌ای با این شناسه وجود ندارد.مقدار sub_category_id را با اندپوینت‌های کاتالوگ بررسی کنید.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PRODUCT_CONFIG400پیکربندی محصول نامعتبر استاین کد دیگر برگردانده نمی‌شود. اکنون برای فیلد الزامی جاافتاده MISSING_REQUIRED_FIELD و برای محصولی که فعلاً قابل فروش نیست PRODUCT_UNAVAILABLE برمی‌گردد.به‌جای این خطا، مدیریت پاسخ‌های خطای MISSING_REQUIRED_FIELD و PRODUCT_UNAVAILABLE را در پیاده‌سازی خودتان پیش‌بینی کنید.دیگر برگردانده نمی‌شود؛ جایگزین: MISSING_REQUIRED_FIELD
INVALID_PAGINATION400پارامترهای صفحه‌بندی نامعتبر استمقدار page یا limit خارج از محدوده مجاز است.page را ۱ یا بیشتر و limit را بین ۱ تا ۱۰۰ قرار دهید.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_DATE_FORMAT400قالب تاریخ نامعتبر استمقدار ارسال‌شده برای پارامتر created_after یا created_before، تاریخی معتبر در قالب استاندارد ISO 8601 نیست.از قالب ISO 8601 استفاده کنید: 2024-01-01T00:00:00Z.action: FIX_INPUT · retryable: false · retry_after: null

اعتبارسنجی بازیکن (400 / 429 / 503)

کدHTTPیعنی چهچگونه رفع می‌شود
PLAYER_NOT_FOUND400بازیکن پیدا نشدبازی تأیید کرده است که این شناسه بازیکن وجود ندارد. این کد فقط با پاسخ قطعی بازی برمی‌گردد؛ اگر بررسی شناسه ممکن نباشد، PLAYER_CHECK_UNAVAILABLE دریافت می‌کنید.درستی شناسه بازیکن را بررسی کنید و ببینید آیا این بازی به zone_id نیاز دارد یا نه.action: FIX_INPUT · retryable: false · retry_after: null
PLAYER_CHECK_UNAVAILABLE503فعلاً امکان بررسی شناسه بازیکن در این بازی نیستدر حال حاضر شناسه‌های بازیکن این بازی قابل بررسی نیستند. توجه کنید که این شناسه بازیکن رد نشده است.پس از گذشت retry_after ثانیه، همان درخواست را دوباره بفرستید. به مشتری خود نگویید که شناسه اشتباه است.action: RETRY_LATER · retryable: true · retry_after: 60
PLAYER_BUSY429این شناسه بازیکن در حال بررسی استدرخواست دیگری برای همین شناسه بازیکن هنوز در حال بررسی است.درخواست را بعد از retry_after ثانیه دوباره ارسال کنید.action: RETRY_SOON · retryable: true · retry_after: 5
PLAYER_VALIDATION_FAILED400اعتبارسنجی بازیکن ناموفق بوددیگر از این کد استفاده نمی‌شود. شناسه بازیکنی که فعلاً قابل بررسی نباشد، پاسخ PLAYER_CHECK_UNAVAILABLE (HTTP 503) می‌گیرد.به‌جای این خطا، پاسخ PLAYER_CHECK_UNAVAILABLE را در پیاده‌سازی‌تان مدیریت کنید.دیگر برگردانده نمی‌شود؛ جایگزین: PLAYER_CHECK_UNAVAILABLE
REGION_MISMATCH400این محصول به منطقه این بازیکن ارسال نمی‌شودبازیکن در منطقه‌ای است که این محصول به آن تحویل داده نمی‌شود. خطا شامل player_region و player_name است.محصول مخصوص منطقه بازیکن را انتخاب کنید.action: CHOOSE_OTHER · retryable: false · retry_after: null

قواعد تجاری (400 / 409)

کدHTTPیعنی چهچگونه رفع می‌شود
INSUFFICIENT_BALANCE400موجودی کیف پول کافی نیستکیف پول شما برای تکمیل این سفارش موجودی کافی ندارد.پیش از ثبت سفارش، کیف پول خود را از صفحه Reload شارژ کنید.action: TOP_UP · retryable: false · retry_after: null
OUT_OF_STOCK400موجودی این محصول تمام شده استمحصول درخواستی در حال حاضر موجود نیست.بعداً دوباره امتحان کنید یا محصول دیگری انتخاب کنید.action: RETRY_LATER · retryable: true · retry_after: null
INSUFFICIENT_STOCK400تعداد موجود کمتر از مقدار درخواستی استتعداد واحدهای موجود کمتر از مقداری است که در سفارش خواسته‌اید. برخلاف OUT_OF_STOCK، این مورد قابل رفع است: error.max_quantity نشان می‌دهد همین حالا چند واحد را می‌توان سفارش داد. هیچ مبلغی کسر نشده است.سفارش را دوباره با تعداد error.max_quantity یا کمتر ارسال کنید.action: FIX_INPUT · retryable: false · retry_after: null
PRODUCT_UNAVAILABLE409این محصول موقتاً در دسترس نیستمحصول وجود دارد، اما فعلاً قابل فروش نیست.کمی بعد دوباره تلاش کنید یا محصول دیگری را انتخاب کنید.action: RETRY_LATER · retryable: true · retry_after: null
PRICING_UPDATING409قیمت محصول در حال به‌روزرسانی استقیمت این محصول در حال تازه شدن است.پس از retry_after ثانیه همان درخواست را دوباره بفرستید و سپس قیمت را دوباره بررسی کنید.action: RETRY_SOON · retryable: true · retry_after: 30
OFFER_NOT_FOUND400این پیشنهاد برای این حساب بازیکن در دسترس نیستیک پیشنهاد یک‌باره (مثلاً پاداش اولین شارژ) برای این حساب بازیکن در دسترس نیست؛ ممکن است قبلاً استفاده شده باشد.محصول دیگری برای این بازیکن انتخاب کنید.action: CHOOSE_OTHER · retryable: false · retry_after: null
DUPLICATE_ORDER409شناسه سفارش تکراری استسفارشی با این UUID از قبل وجود دارد. این خطا برای جلوگیری از ثبت تکراری (idempotency) است.برای سفارش جدید یک UUID تازه بسازید. اگر این خطا را هنگام تلاش مجدد می‌گیرید، یعنی تلاش اول ثبت شده است: به جای ساختن سفارش دیگر، همان سفارش را با GET /orders/{orderId} بخوانید.action: CHECK_ORDER · retryable: false · retry_after: null
PRICE_INCREASED400قیمت بیش از مقدار مورد انتظار بالا رفته استقیمت واحد فعلی از expected_unit_price که ارسال کرده‌اید بیشتر است.آخرین قیمت را با فراخوانی GET /catalog/subcategory/:id/price دریافت کنید، سپس مقدار فیلد expected_unit_price را در درخواست سفارش با همین قیمت تازه به‌روزرسانی کنید.action: FIX_INPUT · retryable: false · retry_after: null
SUBCATEGORY_DISABLED400زیردسته غیرفعال استاین خطا دیگر برگردانده نمی‌شود. محصولی که فعلاً قابل فروش نیست، با PRODUCT_UNAVAILABLE (HTTP 409) پاسخ می‌دهد.این کد را کنار بگذارید و خطای PRODUCT_UNAVAILABLE را مدیریت کنید.دیگر برگردانده نمی‌شود؛ جایگزین: PRODUCT_UNAVAILABLE

یافت نشد (404)

کدHTTPیعنی چهچگونه رفع می‌شود
ORDER_NOT_FOUND404سفارش پیدا نشدهیچ سفارشی با این شناسه وجود ندارد.درستی شناسه سفارش را بررسی کنید.action: FIX_INPUT · retryable: false · retry_after: null
ITEM_NOT_FOUND404آیتم پیدا نشدآیتم درخواستی در کاتالوگ وجود ندارد.برای پیدا کردن شناسه‌های معتبر آیتم، از endpointهای کاتالوگ استفاده کنید.action: FIX_INPUT · retryable: false · retry_after: null
NO_REQUIREMENTS_FOUND404برای این دسته اطلاعات موردنیازی پیدا نشدفعلاً هیچ اطلاعات موردنیاز بازیکن برای این دسته قابل ارائه نیست.کمی بعد دوباره امتحان کنید یا دسته دیگری را برگزینید.action: RETRY_LATER · retryable: true · retry_after: null
ITEM_NOT_AVAILABLE404آیتم در دسترس نیستاین کد خطا دیگر ارسال نمی‌شود. آیتمی که وجود دارد اما فعلاً قابل فروش نیست، با PRODUCT_UNAVAILABLE (HTTP 409) پاسخ می‌دهد.این کد را کنار بگذارید و خطای PRODUCT_UNAVAILABLE را مدیریت کنید.دیگر برگردانده نمی‌شود؛ جایگزین: PRODUCT_UNAVAILABLE

اعتبارسنجی درخواست گروهی (400)

کدHTTPیعنی چهچگونه رفع می‌شود
INVALID_ORDER_IDS_FORMAT400قالب order_ids نامعتبر استفیلد order_ids باید آرایه‌ای از رشته‌ها باشد.order_ids را به این شکل ارسال کنید: { "order_ids": ["uuid1", "uuid2"] }.action: FIX_INPUT · retryable: false · retry_after: null
EMPTY_ORDER_IDS400آرایه order_ids خالی استآرایه order_ids نباید خالی باشد.دست‌کم یک شناسه سفارش در آرایه قرار دهید.action: FIX_INPUT · retryable: false · retry_after: null
TOO_MANY_ORDER_IDS400تعداد شناسه‌های سفارش زیاد استدر هر درخواست حداکثر ۵۰ شناسه سفارش را می‌توان بررسی کرد.درخواست خود را به چند درخواست با حداکثر ۵۰ شناسه تقسیم کنید.action: FIX_INPUT · retryable: false · retry_after: null

محدودیت تعداد درخواست (429)

کدHTTPیعنی چهچگونه رفع می‌شود
RATE_LIMIT_EXCEEDED429از سقف تعداد درخواست عبور کرده‌ایدشما از سقف مجاز درخواست‌ها برای این مسیر فراتر رفته‌اید. محدودیت‌های دقیقه‌ای (کاتالوگ، سفارش‌ها و حساب کاربری) در هر پاسخ هدرهای X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset را می‌فرستند و فیلد details در بدنه پاسخ خطا نیز مقادیر limit، remaining (برابر ۰)، retry_after و window_seconds را تکرار می‌کند. اما POST /player/validate به‌جای این محدودیت‌ها با سهمیه روزانه بررسی بازیکن شما سنجیده می‌شود: این مسیر هیچ‌یک از هدرهای X-RateLimit را نمی‌فرستد و پاسخ 429 آن مقادیر limit، current، remaining، reset_at و reset_in_seconds را داخل شیء error برمی‌گرداند. در هر دو حالت، مقدار error.retry_after و هدر Retry-After تعداد ثانیه‌هایی را نشان می‌دهند که باید پیش از تلاش دوباره صبر کنید.پیش از تلاش دوباره، به اندازه ثانیه‌های retry_after یا هدر Retry-After صبر کنید. در endpointهای دقیقه‌ای، X-RateLimit-Remaining را زیر نظر داشته باشید تا اصلاً به سقف نرسید.action: RETRY_LATER · retryable: true · retry_after: ثانیه تا بازنشانی

خطای سمت سرور (5xx)

کدHTTPیعنی چهچگونه رفع می‌شود
INTERNAL_ERROR500خطای داخلی سرورخطای غیرمنتظره‌ای در سرور رخ داد.درخواست را پس از retry_after ثانیه دوباره بفرستید. برای POST /orders/create از همان order_id قبلی استفاده کنید تا سفارش هرگز دو بار ثبت نشود. اگر مشکل ادامه داشت، با پشتیبانی تماس بگیرید.action: RETRY_LATER · retryable: true · retry_after: 30
SERVICE_UNAVAILABLE503سرویس موقتاً در دسترس نیستاین خطا دیگر برگردانده نمی‌شود. خطای سمت سرور با INTERNAL_ERROR (HTTP 500) پاسخ داده می‌شود؛ تنها پاسخ 503، PLAYER_CHECK_UNAVAILABLE است که وقتی شناسه بازیکن فعلاً قابل بررسی نیست برگردانده می‌شود.این کد را کنار بگذارید و مدیریت خطاهای INTERNAL_ERROR و PLAYER_CHECK_UNAVAILABLE را در برنامه خود پیاده‌سازی کنید.دیگر برگردانده نمی‌شود؛ جایگزین: INTERNAL_ERROR

تازه با پلتفرم آشنا شده‌اید؟ از معرفی API شارژ بازی برای نمایندگان فروش شروع کنید، یا معرفی برنامه نمایندگی SHOP2TOPUP را بخوانید تا ببینید حساب شریک چگونه کار می‌کند.

مرجع کدهای خطای API — هر کد و راه حل آن