ข้อผิดพลาด

โครงสร้างของ error response รหัส HTTP และรหัสข้อผิดพลาดทั้งหมด

สร้างจาก public-api.md โดยอัตโนมัติเวอร์ชัน 1.2.0ปรับปรุงล่าสุด 2026-09-20

#ข้อผิดพลาดที่ระบบคืนกลับ (Error Responses)

ข้อผิดพลาดทั้งหมดมีรูปแบบนี้:

json

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": { "reason": "…", "trace_id": "…" }
}

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": { "reason": "…", "trace_id": "…" }
}

ฟิลด์ details มีหรือไม่มีก็ได้ เมื่อมีอาจบรรจุ reason (คำอธิบายที่ปลอดภัยต่อการแสดงผล จากระบบชำระเงินหรือผู้ให้บริการ) และ trace_id — ให้แจ้ง trace_id เมื่อติดต่อฝ่ายสนับสนุน ค่าเดียวกันนี้ถูกคืนมาใน response header X-Request-ID ของทุกคำขอ

กรณีที่การตรวจสอบข้อมูลของ deposit/withdraw ไม่ผ่าน ระบบจะใส่ details เป็นหนึ่งรายการ ต่อหนึ่งฟิลด์ที่ไม่ผ่าน โดยใช้ชื่อฟิลด์ JSON เป็นคีย์และอธิบายเป็นภาษาไทย

#รหัสสถานะ HTTP

สถานะ	คำอธิบาย
`200`	สำเร็จ
`201`	สร้างแล้ว (deposit / withdraw)
`400`	คำขอไม่ถูกต้อง — ข้อมูลไม่ผ่านการตรวจสอบหรือผิดกฎทางธุรกิจ
`401`	ไม่ได้รับอนุญาต — ไม่มีหรือไม่ถูกต้องที่คีย์ ลายเซ็น หรือ timestamp
`403`	ต้องห้าม — ร้านค้าไม่ได้เปิดใช้งาน หรือ IP ไม่อยู่ในรายการที่อนุญาต
`404`	ไม่พบข้อมูล
`409`	ขัดแย้ง (เช่นรายการที่ประมวลผลไปแล้ว)
`413`	ข้อมูลใหญ่เกินไป (อัปโหลดสลิปเกิน 10 MB)
`429`	เรียกใช้เกินขีดจำกัด
`500`	ข้อผิดพลาดภายในระบบ
`502`	ติดต่อระบบชำระเงินหรือระบบรายงานไม่ได้
`503`	ใช้งานไม่ได้ชั่วคราว — อยู่ในช่วงปิดปรับปรุงหรือหยุดให้บริการชั่วคราว
`504`	เกตเวย์หมดเวลารอ (รวมถึงสถานการณ์ `timeout` ของ sandbox)

#รหัสข้อผิดพลาด

ที่ออกโดย API gateway:

Code	HTTP	คำอธิบาย
`MISSING_API_KEY`	401	ไม่มี header `X-API-Key`
`MISSING_SIGNATURE`	401	ไม่มี header `X-Signature`
`MISSING_TIMESTAMP`	401	ไม่มี header `X-Timestamp`
`INVALID_TIMESTAMP`	401	`X-Timestamp` ไม่ใช่เวลา Unix ที่ถูกต้อง
`TIMESTAMP_EXPIRED`	401	timestamp อยู่นอกช่วง ±5 นาที
`INVALID_API_KEY`	401	ไม่รู้จัก API key นี้
`INVALID_SIGNATURE`	401	ตรวจสอบลายเซ็นไม่ผ่าน
`MISSING_CONTENT_HASH`	401	ไม่มี `X-Content-SHA256` ในการอัปโหลดสลิป
`UNAUTHORIZED`	401	ระบุร้านค้าจากบริบทการยืนยันตัวตนไม่ได้
`AUTHENTICATION_ERROR`	500	ค้นหาข้อมูลคีย์จากระบบต้นทางไม่สำเร็จ
`MERCHANT_INACTIVE`	403	บัญชีร้านค้าไม่ได้อยู่ในสถานะ `active`
`IP_NOT_WHITELISTED`	403	IP ของผู้เรียกไม่อยู่ในรายการที่คุณอนุญาต
`INVALID_BODY`	400	อ่าน body ของคำขอไม่ได้
`INVALID_REQUEST`	400	body ของคำขอไม่ผ่านการตรวจสอบ
`MISSING_PAYER_INFO`	400	ขาดเฉพาะสามฟิลด์ของผู้ชำระเงินในรายการรับเงิน
`CONTENT_HASH_MISMATCH`	400	ไฟล์ที่อัปโหลดไม่ตรงกับ `X-Content-SHA256`
`FILE_REQUIRED`	400	อัปโหลดสลิปโดยไม่มีส่วน `file`
`FILE_READ_ERROR`	400	อ่านไฟล์ที่อัปโหลดไม่ได้
`FILE_TOO_LARGE`	413	สลิปใหญ่เกิน 10 MB
`RATE_LIMIT_EXCEEDED`	429	เรียกเกินขีดจำกัดของร้านค้า
`TIMEOUT`	504	สถานการณ์ `timeout` ของ sandbox
`UPSTREAM_UNAVAILABLE`	502	ติดต่อระบบชำระเงิน/ระบบรายงานไม่ได้ — เรียกซ้ำได้อย่างปลอดภัย
`INTERNAL_ERROR`	500	ความล้มเหลวที่ไม่คาดคิดจากระบบต้นทาง (มี `trace_id` มาด้วย)

ที่ส่งต่อมาจากระบบชำระเงิน:

Code	HTTP	คำอธิบาย
`INVALID_AMOUNT`	400	จำนวนเงินอยู่นอกช่วงที่บัญชีของคุณอนุญาต
`INSUFFICIENT_BALANCE`	400	ยอดคงเหลือที่ใช้ได้ไม่พอสำหรับยอดถอนบวกค่าธรรมเนียม
`PAYMENT_CANNOT_BE_CANCELLED`	400	รายการไม่ได้อยู่ในสถานะ `pending`
`INVALID_ACCOUNT`	400	บัญชีธนาคารไม่ถูกต้อง (สถานการณ์ `invalid_account` ของ sandbox)
`NOT_ELIGIBLE`	400	อัปโหลดสลิปให้รายการที่ไม่ได้อยู่ในสถานะ `expired`
`EXPIRED_TOO_OLD`	400	อัปโหลดสลิปหลังหมดอายุเกิน 24 ชั่วโมง
`AMOUNT_MISMATCH`, `RECEIVER_NOT_RECOGNIZED`, `SLIP_TOO_OLD`, `SLIP_ALREADY_USED`, `PAYER_BANK_MISMATCH`, `SLIP_INVALID`	400	การตรวจสอบสลิปไม่ผ่าน
`NOT_FOUND`	404	ไม่พบรายการ หรือไม่ใช่รายการของคุณ
`CONFLICT`	409	รายการถูกประมวลผลไปแล้ว
`NO_DEPOSIT_ACCOUNT`	503	ขณะนี้ไม่มีบัญชีรับเงินที่ใช้ได้สำหรับรายการนี้ — ยังไม่ได้ตั้งค่า ถูกพักใช้งานทั้งหมด หรือถึงขีดจำกัดรายวันทั้งหมด เรียกซ้ำได้ หากยังพบปัญหาให้ติดต่อฝ่ายสนับสนุน (ข้อความเป็นภาษาไทย)
`SERVICE_UNAVAILABLE`	503	อยู่ในช่วงปิดปรับปรุง หยุดให้บริการชั่วคราว หรือปิดการรับ/จ่ายเงินของบัญชีคุณ (ข้อความเป็นภาษาไทย)

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

503 อธิบายตัวเองเสมอ ต่างจาก 500 ตรงที่ 503 คือสถานะที่แพลตฟอร์มตั้งใจรายงาน ค่า code และ message จึงส่งถึงคุณตามเดิมและนำไปแสดงให้ผู้ดูแลอ่านได้ ส่วน 500 ที่ไม่มี reason เชิงธุรกิจจะถูกลดรูปเป็นข้อความกลาง ๆ โดยตั้งใจ เพราะข้อความต้นทาง อาจเป็นข้อความข้อผิดพลาดภายในระบบ

รหัสที่เคยปรากฏในเอกสารฉบับก่อน ๆ และ ไม่ได้ ถูกใช้แล้ว: PAYMENT_NOT_FOUND (ปัจจุบันคือ NOT_FOUND), PAYMENT_ERROR, DUPLICATE_REFERENCE (ระบบไม่ตรวจจับ reference_id ซ้ำ) และ INVALID_BANK_CODE (รหัสธนาคารถูกตรวจแค่ความยาว)

หน้านี้แปลจากเอกสารต้นฉบับภาษาอังกฤษ ส่วนที่เป็นค่าทางเทคนิค — path, ชื่อฟิลด์, header, รหัสข้อผิดพลาด และชื่อคอลัมน์ในไฟล์ส่งออก — คงไว้เป็นภาษาอังกฤษตามที่ระบบใช้จริง