Kod ralat dan status HTTP
Setiap kegagalan memulangkan kod tetap yang boleh dibaca mesin, bersama status HTTP. Bina logik anda berdasarkan kod, jangan sekali-kali pada teks mesej. Mesej ditulis untuk manusia dan ayatnya boleh berubah, tetapi kod ialah sebahagian daripada kontrak.
Kesemua 42 kod yang boleh dipulangkan oleh API reseller, dikumpulkan mengikut jenis masalah. Setiap entri menyatakan status HTTP yang menyertainya dan perubahan yang perlu dibuat untuk menyelesaikannya.
Pengesahan (401)
| Kod | Status HTTP | Maksud | Cara mengatasi |
|---|---|---|---|
| MISSING_API_KEY | 401 | Kunci API diperlukanHeader Authorization tidak dihantar, atau formatnya salah. | Sertakan header: Authorization: Bearer <keyId>.<secret>action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_API_KEY | 401 | Kunci API tidak sahKunci API yang diberikan tidak sepadan dengan mana-mana kunci aktif dalam sistem. | Pastikan ID kunci dan secret anda betul. Jana semula kunci di panel API Access jika perlu.action: FIX_INPUT · retryable: false · retry_after: null |
Kebenaran (403)
| Kod | Status HTTP | Maksud | Cara mengatasi |
|---|---|---|---|
| ACCOUNT_DISABLED | 403 | Akaun dinyahaktifkanKod ini tidak lagi dipulangkan. Akaun yang tidak boleh membuat pesanan akan menerima ACCOUNT_FROZEN (HTTP 403). | Kendalikan ACCOUNT_FROZEN sebagai gantinya.Tidak lagi dipulangkan; digantikan oleh ACCOUNT_FROZEN |
| ACCOUNT_FROZEN | 403 | Akaun dibekukanAkaun anda dibekukan buat sementara, biasanya kerana aktiviti yang mencurigakan. | Hubungi pihak sokongan untuk menyahbekukan akaun anda.action: CONTACT_SUPPORT · retryable: false · retry_after: null |
| IP_NOT_ALLOWED | 403 | Alamat IP tiada dalam senarai dibenarkanPermintaan ini datang daripada alamat IP yang tiada dalam senarai IP yang dibenarkan untuk kunci API anda. | Tambah IP server anda ke senarai dibenarkan di panel API Access, atau buang sekatan IP.action: FIX_INPUT · retryable: false · retry_after: null |
Semakan permintaan (400)
| Kod | Status HTTP | Maksud | Cara mengatasi |
|---|---|---|---|
| MISSING_REQUIRED_FIELD | 400 | Medan wajib tiadaSatu medan wajib tiada dalam badan permintaan. Untuk keperluan pemain, details.field menyatakan medan yang tiada. | Semak dokumentasi endpoint serta GET /catalog/category/:categoryId/requirements untuk medan pemain. Kemudian hantar semua medan wajib.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_PARAMETER_FORMAT | 400 | Format parameter tidak sahMedan keperluan diisi dengan format yang salah, contohnya teks dalam medan nombor. Nama medan itu ada dalam details.field. | Semak semula keperluan kategori dan hantar medan itu dalam format yang dikehendaki oleh data_type dan peraturan pengesahannya.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_PARAMETER_VALUE | 400 | Nilai parameter tidak sahNilai medan keperluan tidak dibenarkan, sama ada lebih rendah daripada minimum, lebih tinggi daripada maksimum, atau bukan salah satu pilihan dalam select_options. Medan yang terlibat dinyatakan dalam details.field. | Hantar nilai yang dibenarkan oleh keperluan kategori untuk medan itu.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_PARAMETER_LENGTH | 400 | Panjang parameter tidak sahMedan keperluan lebih pendek atau lebih panjang daripada yang dibenarkan. Medan berkenaan dinyatakan dalam details.field. | Semak min_length / max_length dalam keperluan kategori.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_UUID_FORMAT | 400 | Format UUID tidak sahorder_id bukan dalam format UUID yang sah. | Gunakan mana-mana format UUID yang sah (v1, v4, v7 dan lain-lain), iaitu xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_QUANTITY | 400 | Kuantiti tidak sahKuantiti mesti integer positif. | Hantar kuantiti dalam bentuk integer, >= 1.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_CATEGORY_ID | 400 | ID kategori tidak sahcategoryId yang diberikan bukan nombor yang sah. | Gunakan Catalog Explorer atau GET /catalog/categories untuk mencari ID kategori yang sah.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_BIG_CATEGORY_ID | 400 | ID kategori utama tidak sahbigCategoryId yang diberikan bukan nombor yang sah. | Dapatkan ID kategori utama yang sah melalui Catalog Explorer atau GET /catalog/big-categories.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_ITEM_ID | 400 | ID item tidak sahID item yang diberikan tidak sah. | Cari ID item yang sah melalui Catalog Explorer atau GET /catalog/subcategories.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_SUBCATEGORY | 400 | Subkategori tidak sahID subkategori tersebut tidak wujud. | Semak sub_category_id menggunakan endpoint katalog.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_PRODUCT_CONFIG | 400 | Konfigurasi produk tidak sahKod ini tidak lagi dikembalikan. Jika medan keperluan tiada, API kini mengembalikan MISSING_REQUIRED_FIELD; jika produk tidak boleh dijual buat masa ini, API mengembalikan PRODUCT_UNAVAILABLE. | Kendalikan MISSING_REQUIRED_FIELD dan PRODUCT_UNAVAILABLE sebagai gantinya.Tidak lagi dipulangkan; digantikan oleh MISSING_REQUIRED_FIELD |
| INVALID_PAGINATION | 400 | Parameter penomboran halaman tidak sahNilai page atau limit berada di luar julat. | Gunakan page >= 1 dan limit antara 1 hingga 100.action: FIX_INPUT · retryable: false · retry_after: null |
| INVALID_DATE_FORMAT | 400 | Format tarikh tidak sahParameter created_after atau created_before bukan tarikh ISO 8601 yang sah. | Gunakan format ISO 8601: 2024-01-01T00:00:00Z.action: FIX_INPUT · retryable: false · retry_after: null |
Semakan pemain (400 / 429 / 503)
| Kod | Status HTTP | Maksud | Cara mengatasi |
|---|---|---|---|
| PLAYER_NOT_FOUND | 400 | Pemain tidak dijumpaiGame telah mengesahkan bahawa ID pemain ini tidak wujud. Kod ini hanya dipulangkan apabila jawapannya disahkan. Jika ID tidak dapat disemak, anda akan menerima PLAYER_CHECK_UNAVAILABLE. | Pastikan ID pemain betul. Semak jika game ini memerlukan zone_id.action: FIX_INPUT · retryable: false · retry_after: null |
| PLAYER_CHECK_UNAVAILABLE | 503 | ID pemain untuk game ini tidak dapat disemak sekarangSemakan ID pemain untuk game ini tidak dapat dibuat pada masa ini. ID pemain tersebut TIDAK ditolak. | Hantar permintaan yang sama sekali lagi selepas retry_after saat. Jangan beritahu pelanggan anda bahawa ID itu salah.action: RETRY_LATER · retryable: true · retry_after: 60 |
| PLAYER_BUSY | 429 | ID pemain ini sedang disemakSatu lagi permintaan untuk ID pemain yang sama masih dalam semakan. | Hantar semula permintaan selepas retry_after saat.action: RETRY_SOON · retryable: true · retry_after: 5 |
| PLAYER_VALIDATION_FAILED | 400 | Pengesahan pemain gagalKod ini tidak dipulangkan lagi. Bagi ID pemain yang tidak dapat disemak buat masa ini, API memulangkan PLAYER_CHECK_UNAVAILABLE (HTTP 503). | Uruskan PLAYER_CHECK_UNAVAILABLE sebagai gantinya.Tidak lagi dipulangkan; digantikan oleh PLAYER_CHECK_UNAVAILABLE |
| REGION_MISMATCH | 400 | Produk ini tidak boleh dihantar ke region pemain iniProduk ini tidak boleh dihantar ke region pemain tersebut. Ralat ini menyertakan player_region dan player_name. | Pilih produk untuk region pemain tersebut.action: CHOOSE_OTHER · retryable: false · retry_after: null |
Peraturan perniagaan (400 / 409)
| Kod | Status HTTP | Maksud | Cara mengatasi |
|---|---|---|---|
| INSUFFICIENT_BALANCE | 400 | Baki dompet tidak mencukupiBaki dompet anda tidak cukup untuk membayar pesanan ini. | Top up dompet anda di halaman Reload sebelum membuat pesanan.action: TOP_UP · retryable: false · retry_after: null |
| OUT_OF_STOCK | 400 | Stok produk habisProduk yang diminta kehabisan stok buat masa ini. | Cuba lagi nanti atau pilih produk lain.action: RETRY_LATER · retryable: true · retry_after: null |
| INSUFFICIENT_STOCK | 400 | Unit yang ada kurang daripada yang dimintaBilangan unit yang ada kurang daripada kuantiti dalam pesanan anda. Berbeza dengan OUT_OF_STOCK, ralat ini boleh anda atasi: error.max_quantity menunjukkan bilangan unit yang boleh dipesan sekarang. Tiada caj dikenakan. | Hantar semula pesanan dengan kuantiti error.max_quantity atau kurang.action: FIX_INPUT · retryable: false · retry_after: null |
| PRODUCT_UNAVAILABLE | 409 | Produk ini tidak tersedia buat sementara waktuProduk ini wujud tetapi tidak boleh dijual pada masa ini. | Cuba lagi nanti, atau pilih produk lain.action: RETRY_LATER · retryable: true · retry_after: null |
| PRICING_UPDATING | 409 | Harga produk sedang dikemas kiniHarga produk ini sedang dikemas kini. | Hantar permintaan yang sama sekali lagi selepas retry_after saat, kemudian semak harga semula.action: RETRY_SOON · retryable: true · retry_after: 30 |
| OFFER_NOT_FOUND | 400 | Tawaran ini tidak tersedia untuk akaun pemain iniTawaran sekali sahaja (contohnya bonus top up pertama) tidak tersedia untuk akaun pemain ini. Mungkin tawaran itu sudah digunakan. | Pilih produk lain untuk pemain ini.action: CHOOSE_OTHER · retryable: false · retry_after: null |
| DUPLICATE_ORDER | 409 | ID pesanan penduaPesanan dengan UUID ini sudah wujud. UUID yang sama tidak boleh digunakan untuk membuat pesanan sekali lagi. | Jana UUID baharu untuk pesanan baharu. Jika ralat ini muncul semasa cubaan semula, cubaan pertama sudah diterima: semak pesanan tersebut menggunakan GET /orders/{orderId}, bukan cipta pesanan lain.action: CHECK_ORDER · retryable: false · retry_after: null |
| PRICE_INCREASED | 400 | Harga telah naik melebihi jangkaanHarga seunit semasa lebih tinggi daripada expected_unit_price yang anda berikan. | Dapatkan harga terkini dengan GET /catalog/subcategory/:id/price dan kemas kini expected_unit_price.action: FIX_INPUT · retryable: false · retry_after: null |
| SUBCATEGORY_DISABLED | 400 | Subkategori dinyahaktifkanKod ini tidak dipulangkan lagi. Bagi produk yang tidak boleh dijual buat masa ini, API memulangkan PRODUCT_UNAVAILABLE (HTTP 409). | Sebaliknya, kendalikan ralat PRODUCT_UNAVAILABLE.Tidak lagi dipulangkan; digantikan oleh PRODUCT_UNAVAILABLE |
Tidak dijumpai (404)
| Kod | Status HTTP | Maksud | Cara mengatasi |
|---|---|---|---|
| ORDER_NOT_FOUND | 404 | Pesanan tidak dijumpaiTiada pesanan dengan ID pesanan tersebut. | Pastikan ID pesanan betul.action: FIX_INPUT · retryable: false · retry_after: null |
| ITEM_NOT_FOUND | 404 | Item tidak dijumpaiItem katalog yang diminta tidak wujud. | Gunakan endpoint katalog untuk mencari ID item yang sah.action: FIX_INPUT · retryable: false · retry_after: null |
| NO_REQUIREMENTS_FOUND | 404 | Tiada keperluan untuk kategori iniBuat masa ini, tiada keperluan pemain untuk kategori ini. | Cuba lagi nanti, atau pilih kategori lain.action: RETRY_LATER · retryable: true · retry_after: null |
| ITEM_NOT_AVAILABLE | 404 | Item tidak tersediaKod ini tidak dipulangkan lagi. Bagi item yang wujud tetapi tidak boleh dijual sekarang, API memulangkan PRODUCT_UNAVAILABLE (HTTP 409). | Sebaliknya, kendalikan PRODUCT_UNAVAILABLE.Tidak lagi dipulangkan; digantikan oleh PRODUCT_UNAVAILABLE |
Semakan permintaan pukal (400)
| Kod | Status HTTP | Maksud | Cara mengatasi |
|---|---|---|---|
| INVALID_ORDER_IDS_FORMAT | 400 | Format order_ids tidak sahMedan order_ids mestilah array yang mengandungi string. | Hantar order_ids dalam bentuk ini: { "order_ids": ["uuid1", "uuid2"] }.action: FIX_INPUT · retryable: false · retry_after: null |
| EMPTY_ORDER_IDS | 400 | Array order_ids kosongArray order_ids tidak boleh kosong. | Masukkan sekurang-kurangnya satu ID pesanan dalam array.action: FIX_INPUT · retryable: false · retry_after: null |
| TOO_MANY_ORDER_IDS | 400 | Terlalu banyak ID pesananMaksimum 50 ID pesanan boleh disemak sekali gus. | Bahagikan permintaan anda kepada beberapa batch, dengan maksimum 50 bagi setiap batch.action: FIX_INPUT · retryable: false · retry_after: null |
Had kadar (429)
| Kod | Status HTTP | Maksud | Cara mengatasi |
|---|---|---|---|
| RATE_LIMIT_EXCEEDED | 429 | Terlalu banyak permintaanAnda telah melebihi had untuk endpoint ini. Bagi bucket per minit (catalog, orders, account), setiap respons menyertakan X-RateLimit-Limit, X-RateLimit-Remaining dan X-RateLimit-Reset. Medan details turut memaparkan limit, remaining (0), retry_after dan window_seconds. POST /player/validate pula menggunakan kuota semakan pemain harian anda: responsnya tidak menyertakan header X-RateLimit, dan respons 429 mengandungi limit, current, remaining, reset_at dan reset_in_seconds dalam error. Dalam kedua-dua kes, error.retry_after dan header Retry-After menyatakan tempoh menunggu dalam saat. | Tunggu selama bilangan saat yang dinyatakan dalam retry_after atau header Retry-After sebelum mencuba semula. Untuk endpoint dengan had per minit, pantau X-RateLimit-Remaining bagi mengelakkan permintaan mencecah had.action: RETRY_LATER · retryable: true · retry_after: saat sebelum set semula |
Ralat server (5xx)
| Kod | Status HTTP | Maksud | Cara mengatasi |
|---|---|---|---|
| INTERNAL_ERROR | 500 | Ralat dalaman serverBerlaku ralat yang tidak dijangka pada server. | Hantar semula permintaan selepas retry_after saat. Untuk POST /orders/create, guna semula order_id yang sama supaya pesanan tidak akan dicipta dua kali. Jika masalah berterusan, hubungi sokongan.action: RETRY_LATER · retryable: true · retry_after: 30 |
| SERVICE_UNAVAILABLE | 503 | Perkhidmatan tidak tersedia buat sementaraKod ini tidak lagi dikembalikan. Jika berlaku ralat pada server, responsnya ialah INTERNAL_ERROR (HTTP 500). Hanya PLAYER_CHECK_UNAVAILABLE menggunakan HTTP 503, apabila ID pemain tidak dapat disemak buat masa ini. | Kendalikan INTERNAL_ERROR dan PLAYER_CHECK_UNAVAILABLE sebagai gantinya.Tidak lagi dipulangkan; digantikan oleh INTERNAL_ERROR |
Jika anda baru di platform ini, mulakan dengan gambaran keseluruhan API top up game untuk reseller, atau baca gambaran keseluruhan program reseller SHOP2TOPUP untuk mengetahui cara akaun rakan kongsi berfungsi.