Error Codes Reference
reference.errorCodesPageDesc
บางรหัสยืนยันจริงจาก testnet แล้ว
รหัสที่ติด VERIFIED ทดสอบกับ API จริงเรียบร้อย — รหัสที่เหลืออ้างอิงจากโค้ด backend แต่ยังไม่ได้ทดสอบกับ API จริง
แสดง 23 / 23 รายการ
| Code | HTTP | Error | ความหมาย & การแก้ไข |
|---|---|---|---|
| — | 401 | UNAUTHORIZEDVerified ไม่ได้รับอนุญาต | ไม่ได้ส่ง x-api-key, key ไม่ถูกต้องหรือหมดอายุ หรือบัญชีร้านถูกปิด — error เป็นข้อความ "ไม่ได้รับอนุญาต" ไม่มี code ตรวจ x-api-key ว่าถูกต้องและใช้กับ environment เดียวกัน |
2004 | 400 | NOT_FOUND_TIMESTAMPVerified ไม่พบการประทับเวลา | ไม่ได้ส่ง x-timestamp หรือค่าไม่ใช่ตัวเลข ส่ง x-timestamp เป็น Unix timestamp หน่วยมิลลิวินาที |
2005 | 400 | NOT_FOUND_SIGNATURE ไม่พบลายเซ็น | ไม่ได้ส่ง x-signature หรือความยาวไม่ใช่ 64 ตัวอักษร (HMAC-SHA256 แบบ hex) ส่ง x-signature เป็น hex 64 ตัวอักษร |
1010 | 400 | API_KEY_NOT_FOUNDVerified ไม่พบ API คีย์ | header ครบแต่ไม่พบ x-api-key นี้ในระบบ ตรวจว่า key ถูกต้องและยังไม่ถูกลบหรือสร้างใหม่แทน |
2006 | 400 | INVALID_SIGNATURE ลายเซ็นไม่ถูกต้อง | x-signature ไม่ตรงกับที่ server คำนวณได้ ตรวจ secret key และรูปแบบ timestamp|method|fullUrl|JSON.stringify(body || "") |
2003 | 403 | IP_NOT_FOUND_WHITELIST ไม่พบ IP ในรายการที่อนุญาต | เรียก endpoint ถอนเงินจาก IP ที่ร้านไม่ได้เพิ่มไว้ใน whitelist เพิ่ม IP ของ server ใน whitelist ของร้าน |
2044 | 403 | MTLS_CLIENT_CERT_REQUIRED ต้องใช้ใบรับรอง client | API key นี้ถูกบังคับใช้ mTLS แต่คำขอมาโดยไม่มีใบรับรอง หรือไม่ได้ส่งผ่าน host api-mtls.trustsig.xyz สาเหตุอยู่ใน error.detail เปลี่ยน base URL เป็น https://api-mtls.trustsig.xyz และแนบใบรับรอง ดูหน้า mTLS Certificate |
2045 | 403 | MTLS_CLIENT_CERT_MISMATCH ใบรับรอง client ถูกปฏิเสธ | มีใบรับรองแนบมา แต่ระบบไม่รู้จัก ถูกเพิกถอน หมดอายุ หรือเป็นขององค์กรอื่นที่ไม่ตรงกับ API key สาเหตุอยู่ใน error.detail ติดต่อทีมงานพร้อม fingerprint และวันหมดอายุของใบรับรอง |
999 | 403 | client certificate requiredVerified ถูกปฏิเสธที่ขอบเครือข่าย (mTLS) | พบเฉพาะบน host api-mtls.trustsig.xyz เมื่อไม่ได้แนบใบรับรอง client หรือใบรับรองไม่ได้ออกโดย CA ของระบบ คำขอไปไม่ถึง API และ response มี code อยู่ชั้นนอกสุด ไม่มี object error เรียก GET /__mtls เพื่อดูว่าระบบเห็นใบรับรองอย่างไร |
| — | 422 | VALIDATION_ERRORVerified Field validation failed | API ตอบ error เป็น string format "field: rule" เช่น "amount: Required" หรือ "order_id: Required" บอกเฉพาะ field แรกที่ผิด parse string เพื่อหา field ที่ผิด แล้วแก้ payload |
| — | 404 | NOT_FOUNDVerified Endpoint ไม่มีอยู่ | เรียก URL ที่ไม่มี — error เป็น string "ไม่พบข้อมูล" ตรวจ path และ method ของ endpoint ให้ถูกต้อง |
1003 | 429 | TOO_MANY_REQUESTS คำขอมากเกินไป | ส่ง request เกิน limit — error มี retry_after (วินาที) และ retry_at และมี header Retry-After รอตาม retry_after แล้วค่อยส่งใหม่ |
9000 | 400 | PAYMENT_EXISTS มีการชำระเงินนี้อยู่แล้ว | สร้าง invoice ด้วย order_id ที่เคยใช้แล้ว ใช้ order_id ใหม่ทุกครั้ง |
9002 | 400 | PAYMENT_NOT_FOUNDVerified ไม่พบการชำระเงิน | ID ที่ระบุไม่มีในระบบ (สำหรับ /v1/payment/info, /v1/payment/cancel) — ตอบ 400 ไม่ใช่ 404 ตรวจ payment id ว่าถูกต้องและอยู่ใน environment เดียวกัน |
10000 | 400 | WITHDRAWAL_NOT_FOUNDVerified ไม่พบการถอนเงิน | id หรือ order_id ของ withdrawal ไม่มีในระบบ — ตอบ 400 ไม่ใช่ 404 เช็ค id/order_id หรือเรียก /v1/withdrawal/list เพื่อหา |
10002 | 400 | WITHDRAWAL_INVALID_ADDRESS ที่อยู่สำหรับถอนไม่ถูกต้อง | withdrawal_address ว่าง หรือเลขพร้อมเพย์ไม่ตรงกับ promptpay_id_type — detail บอกสาเหตุ ตรวจเลขบัญชีหรือเลขพร้อมเพย์และชนิดที่ส่งมา |
10005 | 400 | WITHDRAWAL_ORDER_ID_EXISTS order_id ของรายการถอนซ้ำ | มีรายการถอนที่ใช้ order_id นี้แล้ว ใช้ order_id ใหม่ทุกครั้ง |
10046 | 400 | WITHDRAWAL_DUPLICATE_ORDER_ID order_id ซ้ำ (ส่งพร้อมกัน) | ส่ง order_id เดียวกันพร้อมกันสองครั้ง ตัวที่สองจะได้ code นี้ ตรวจด้วย /v1/withdrawal/info?order_id=... ว่าตัวแรกสร้างสำเร็จแล้วหรือยัง |
10067 | 400 | WITHDRAWAL_AMOUNT_NOT_ROUND ยอดถอนต้องเป็นจำนวนเต็มร้อย | ยอดถอน THB ไม่ใช่จำนวนเต็มร้อย เช่น 567 หรือ 1105 ปัดยอดเป็นจำนวนเต็มร้อยก่อนส่ง เช่น 500 หรือ 1100 |
38045 | 409 | P2P_DUPLICATE_ORDER_ID order_id ซ้ำ | order_id นี้มี P2P session ที่ยังไม่หมดอายุอยู่แล้ว ใช้ order_id ใหม่ หรือรอให้ session เดิมหมดอายุ |
1002 | 500 | INTERNAL_SERVER_ERROR Server error ที่ไม่ระบุ | เกิดข้อผิดพลาดที่ฝั่ง server ลองใหม่ภายหลัง — ถ้าเกิดบ่อยแจ้ง support พร้อม timestamp ของ request |
| — | 502 | UPSTREAM_ERROR Upstream service ไม่ตอบกลับ | Bank/blockchain provider ติดขัด รอ retry — ถ้าเกี่ยวกับ payment ระบบจะ retry อัตโนมัติ |
| — | 503 | SERVICE_UNAVAILABLE Service กำลังปรับปรุง | อยู่ในช่วง maintenance หรือ deploy รอตามเวลาที่ประกาศ |
รูปแบบ Error Response
API ตอบ error เป็น 2 รูปแบบ ขึ้นอยู่กับ HTTP status — code consumer ต้อง handle ทั้งสองแบบ ข้อความเป็นภาษาไทยโดยค่าเริ่มต้น ถ้าส่ง header Accept-Language: en จะได้ภาษาอังกฤษ
Format A — Plain string (401 / 404 path ไม่มี / 422 validation)
{
"error": "ไม่ได้รับอนุญาต", // string — ไม่มี code
"success": false
}Format B — Structured object (400 / 403 / 409 / 429 / 500)
{
"error": {
"code": 10005, // numeric error code (ดูตารางด้านบน)
"message": "รหัสคำสั่งซื้อถอนเงินมีอยู่แล้ว",
"detail": "Order ID already exists" // มีบางกรณี — รายละเอียดภาษาอังกฤษ
},
"data": { }, // มีบางกรณี — ข้อมูลประกอบ เช่น ยอดที่แนะนำ
"success": false
}429 มี retry_after (วินาที) และ retry_at อยู่ใน object error เพิ่มเติม
กรณีพิเศษ — ถูกปฏิเสธที่ขอบเครือข่าย (เฉพาะ host mTLS)
{
"success": false,
"code": 999, // อยู่ชั้นนอกสุด ไม่มี object error
"message": "client certificate required"
} ร้านที่เรียกผ่าน api-mtls.trustsig.xyz จะพบรูปแบบนี้เมื่อไม่ได้แนบใบรับรอง client คำขอไปไม่ถึง API ดูหน้า mTLS Certificate
วิธี handle ใน TypeScript
type ApiError = string | { code: number; message: string; detail?: string };
const message = typeof err === 'string' ? err : err.message;
const code = typeof err === 'string' ? null : err.code;