รหัสข้อผิดพลาดและสถานะ HTTP

เมื่อคำขอล้มเหลว ระบบจะส่งรหัสที่โปรแกรมอ่านได้และคงที่มาพร้อมสถานะ HTTP ทุกครั้ง ให้เขียนเงื่อนไขโดยอิงรหัส อย่าอิงข้อความ เพราะข้อความเขียนไว้ให้คนอ่านและอาจปรับถ้อยคำได้ ส่วนรหัสเป็นส่วนหนึ่งของข้อกำหนด API

รหัสทั้งหมด 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 ที่ส่งมาไม่ตรงกับคีย์ใดที่ใช้งานอยู่ในระบบตรวจสอบ key ID และ secret ให้ถูกต้อง หากจำเป็นให้สร้างคีย์ใหม่จากหน้า API Accessaction: 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 หรือยกเลิกการจำกัด IPaction: FIX_INPUT · retryable: false · retry_after: null

การตรวจสอบคำขอ (400)

โค้ดรหัสสถานะ HTTPความหมายวิธีแก้
MISSING_REQUIRED_FIELD400ขาดฟิลด์ที่จำเป็นbody ของคำขอขาดฟิลด์ที่จำเป็น หากเป็นข้อมูลผู้เล่น 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 ซึ่งเป็นอักขระ 32 ตัว แบ่งเป็นชุด 8-4-4-4-12 คั่นด้วยขีดกลางaction: FIX_INPUT · retryable: false · retry_after: null
INVALID_QUANTITY400จำนวนไม่ถูกต้องจำนวนต้องเป็นจำนวนเต็มบวกระบุจำนวนเป็นจำนวนเต็มที่ >= 1action: FIX_INPUT · retryable: false · retry_after: null
INVALID_CATEGORY_ID400ID หมวดหมู่ไม่ถูกต้องcategoryId ที่ส่งมาไม่ใช่ตัวเลขที่ถูกต้องเปิด Catalog Explorer หรือเรียก GET /catalog/categories เพื่อดูรายการหมวดหมู่ แล้วเลือกรหัสหมวดหมู่ที่ถูกต้องจากรายการนั้นมาใส่ในคำขอaction: FIX_INPUT · retryable: false · retry_after: null
INVALID_BIG_CATEGORY_ID400ID หมวดหมู่หลักไม่ถูกต้องbigCategoryId ที่ส่งมาไม่ใช่ตัวเลขที่ถูกต้องดูรายการหมวดหมู่หลักได้ใน Catalog Explorer หรือเรียก GET /catalog/big-categories แล้วนำรหัสหมวดหมู่หลักที่ถูกต้องจากรายการนั้นมาใส่ในคำขอaction: FIX_INPUT · retryable: false · retry_after: null
INVALID_ITEM_ID400ID สินค้าไม่ถูกต้องID สินค้าที่ส่งมาใช้ไม่ได้หารหัสสินค้าที่ถูกต้องได้จาก Catalog Explorer หรือเรียก GET /catalog/subcategories เพื่อดูรายการสินค้า แล้วนำรหัสจากรายการนั้นมาใส่ในคำขอaction: FIX_INPUT · retryable: false · retry_after: null
INVALID_SUBCATEGORY400หมวดหมู่ย่อยไม่ถูกต้องไม่มี ID หมวดหมู่ย่อยนี้ในระบบยืนยันความถูกต้องของ 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 ให้มีค่าตั้งแต่ 1 ขึ้นไป และ limit อยู่ระหว่าง 1 ถึง 100action: FIX_INPUT · retryable: false · retry_after: null
INVALID_DATE_FORMAT400รูปแบบวันที่ไม่ถูกต้องค่าวันที่ที่ส่งมาในพารามิเตอร์ created_after หรือ created_before ไม่ใช่วันที่ที่ถูกต้องตามรูปแบบมาตรฐาน ISO 8601ใช้รูปแบบ ISO 8601 เช่น 2024-01-01T00:00:00Zaction: FIX_INPUT · retryable: false · retry_after: null

การตรวจสอบผู้เล่น (400 / 429 / 503)

โค้ดรหัสสถานะ HTTPความหมายวิธีแก้
PLAYER_NOT_FOUND400ไม่พบผู้เล่นเกมยืนยันแล้วว่าไม่มี ID ผู้เล่นนี้อยู่จริง โค้ดนี้จะส่งกลับเฉพาะเมื่อได้รับคำยืนยันแน่ชัดเท่านั้น หากตรวจสอบ ID ไม่ได้ จะได้ PLAYER_CHECK_UNAVAILABLE แทนตรวจสอบว่า ID ผู้เล่นถูกต้อง และดูว่าเกมนี้ต้องใช้ zone_id ด้วยหรือไม่action: FIX_INPUT · retryable: false · retry_after: null
PLAYER_CHECK_UNAVAILABLE503ขณะนี้ยังตรวจสอบ ID ผู้เล่นของเกมนี้ไม่ได้ระบบยังตรวจสอบ ID ผู้เล่นของเกมนี้ไม่ได้ชั่วคราว โดย ID ผู้เล่นที่ส่งมาไม่ได้ถูกปฏิเสธส่งคำขอเดิมอีกครั้งหลังผ่านไป retry_after วินาที และอย่าแจ้งลูกค้าว่า ID ไม่ถูกต้องaction: RETRY_LATER · retryable: true · retry_after: 60
PLAYER_BUSY429ID ผู้เล่นนี้กำลังอยู่ระหว่างการตรวจสอบมีคำขออื่นของ ID ผู้เล่นเดียวกันที่ยังตรวจสอบไม่เสร็จส่งคำขออีกครั้งเมื่อครบ retry_after วินาทีaction: RETRY_SOON · retryable: true · retry_after: 5
PLAYER_VALIDATION_FAILED400ตรวจสอบผู้เล่นไม่สำเร็จเลิกใช้โค้ดนี้แล้ว กรณีที่ ID ผู้เล่นยังตรวจสอบไม่ได้ในขณะนี้ จะได้ 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_quantityaction: 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_ORDER409ID คำสั่งซื้อซ้ำมีคำสั่งซื้อที่ใช้ 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ไม่พบคำสั่งซื้อไม่มีคำสั่งซื้อที่ตรงกับ ID นี้ตรวจสอบว่า ID คำสั่งซื้อถูกต้องaction: FIX_INPUT · retryable: false · retry_after: null
ITEM_NOT_FOUND404ไม่พบรายการสินค้าไม่มีรายการสินค้าที่ร้องขอในแคตตาล็อกใช้ endpoint ของแคตตาล็อกเพื่อค้นหา ID สินค้าที่ถูกต้องaction: FIX_INPUT · retryable: false · retry_after: null
NO_REQUIREMENTS_FOUND404ไม่พบข้อกำหนดสำหรับหมวดหมู่นี้ขณะนี้หมวดหมู่นี้ยังไม่มีข้อกำหนดข้อมูลผู้เล่นให้ส่งกลับลองใหม่ภายหลัง หรือเลือกหมวดหมู่อื่นaction: RETRY_LATER · retryable: true · retry_after: null
ITEM_NOT_AVAILABLE404สินค้าไม่พร้อมจำหน่ายAPI ไม่ส่งรหัสนี้กลับมาแล้ว หากสินค้ามีอยู่แต่ขายไม่ได้ในขณะนี้ ระบบจะตอบกลับเป็น 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 ที่ว่างเปล่าไม่ได้ระบุ ID คำสั่งซื้อในอาร์เรย์อย่างน้อย 1 รายการaction: FIX_INPUT · retryable: false · retry_after: null
TOO_MANY_ORDER_IDS400จำนวน ID คำสั่งซื้อเกินกำหนดค้นหา ID คำสั่งซื้อได้สูงสุด 50 รายการต่อครั้งแบ่งคำขอเป็นชุดละไม่เกิน 50 รายการ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 (0), retry_after และ window_seconds ซ้ำอีกครั้ง สำหรับ POST /player/validate ระบบจะไม่ใช้โควตารายนาที แต่จะนับตามโควตาการตรวจสอบผู้เล่นรายวันของคุณแทน จึงไม่มีเฮดเดอร์ชุดข้างต้นส่งกลับมา และเมื่อระบบตอบกลับด้วยสถานะ 429 จะมีค่า limit, current, remaining, reset_at และ reset_in_seconds อยู่ภายในฟิลด์ error ทั้งสองกรณี จำนวนวินาทีที่ต้องรอจะอยู่ในค่า error.retry_after และเฮดเดอร์ Retry-Afterรอให้ครบจำนวนวินาทีตามค่า retry_after หรือเฮดเดอร์ Retry-After ก่อนส่งคำขอใหม่ สำหรับเอนด์พอยต์ที่จำกัดจำนวนครั้งต่อนาที ให้คอยดูค่า 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บริการไม่พร้อมใช้งานชั่วคราวAPI ไม่ส่งรหัสนี้กลับมาแล้ว ข้อผิดพลาดฝั่งเซิร์ฟเวอร์จะตอบกลับเป็น INTERNAL_ERROR (HTTP 500) ส่วน 503 มีเพียง PLAYER_CHECK_UNAVAILABLE ซึ่งเกิดเมื่อตรวจสอบ ID ผู้เล่นไม่ได้ในขณะนั้นระบบของคุณควรตรวจจับและจัดการรหัสข้อผิดพลาด INTERNAL_ERROR และ PLAYER_CHECK_UNAVAILABLE แทนรหัสนี้ โดยแยกการจัดการของแต่ละรหัสให้ชัดเจนไม่มีการส่งกลับแล้ว แทนที่ด้วย INTERNAL_ERROR

หากเพิ่งเริ่มใช้แพลตฟอร์ม เริ่มที่หน้าภาพรวม API เติมเกมสำหรับตัวแทนจำหน่าย หรืออ่านภาพรวมโปรแกรมตัวแทนจำหน่ายของ SHOP2TOPUP เพื่อดูว่าบัญชีพาร์ทเนอร์ใช้งานอย่างไร

รหัสข้อผิดพลาดของ API: ทุกรหัสพร้อมวิธีแก้