Error Codes Reference

reference.errorCodesPageDesc

บางรหัสยืนยันจริงจาก testnet แล้ว

รหัสที่ติด VERIFIED ทดสอบกับ API จริงเรียบร้อย — รหัสที่เหลืออ้างอิงจากโค้ด backend แต่ยังไม่ได้ทดสอบกับ API จริง

แสดง 23 / 23 รายการ

CodeHTTPErrorความหมาย & การแก้ไข
—401
UNAUTHORIZEDVerified
ไม่ได้รับอนุญาต

ไม่ได้ส่ง x-api-key, key ไม่ถูกต้องหรือหมดอายุ หรือบัญชีร้านถูกปิด — error เป็นข้อความ "ไม่ได้รับอนุญาต" ไม่มี code

ตรวจ x-api-key ว่าถูกต้องและใช้กับ environment เดียวกัน

2004400
NOT_FOUND_TIMESTAMPVerified
ไม่พบการประทับเวลา

ไม่ได้ส่ง x-timestamp หรือค่าไม่ใช่ตัวเลข

ส่ง x-timestamp เป็น Unix timestamp หน่วยมิลลิวินาที

2005400
NOT_FOUND_SIGNATURE
ไม่พบลายเซ็น

ไม่ได้ส่ง x-signature หรือความยาวไม่ใช่ 64 ตัวอักษร (HMAC-SHA256 แบบ hex)

ส่ง x-signature เป็น hex 64 ตัวอักษร

1010400
API_KEY_NOT_FOUNDVerified
ไม่พบ API คีย์

header ครบแต่ไม่พบ x-api-key นี้ในระบบ

ตรวจว่า key ถูกต้องและยังไม่ถูกลบหรือสร้างใหม่แทน

2006400
INVALID_SIGNATURE
ลายเซ็นไม่ถูกต้อง

x-signature ไม่ตรงกับที่ server คำนวณได้

ตรวจ secret key และรูปแบบ timestamp|method|fullUrl|JSON.stringify(body || "")

2003403
IP_NOT_FOUND_WHITELIST
ไม่พบ IP ในรายการที่อนุญาต

เรียก endpoint ถอนเงินจาก IP ที่ร้านไม่ได้เพิ่มไว้ใน whitelist

เพิ่ม IP ของ server ใน whitelist ของร้าน

2044403
MTLS_CLIENT_CERT_REQUIRED
ต้องใช้ใบรับรอง client

API key นี้ถูกบังคับใช้ mTLS แต่คำขอมาโดยไม่มีใบรับรอง หรือไม่ได้ส่งผ่าน host api-mtls.trustsig.xyz สาเหตุอยู่ใน error.detail

เปลี่ยน base URL เป็น https://api-mtls.trustsig.xyz และแนบใบรับรอง ดูหน้า mTLS Certificate

2045403
MTLS_CLIENT_CERT_MISMATCH
ใบรับรอง client ถูกปฏิเสธ

มีใบรับรองแนบมา แต่ระบบไม่รู้จัก ถูกเพิกถอน หมดอายุ หรือเป็นขององค์กรอื่นที่ไม่ตรงกับ API key สาเหตุอยู่ใน error.detail

ติดต่อทีมงานพร้อม fingerprint และวันหมดอายุของใบรับรอง

999403
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 ให้ถูกต้อง

1003429
TOO_MANY_REQUESTS
คำขอมากเกินไป

ส่ง request เกิน limit — error มี retry_after (วินาที) และ retry_at และมี header Retry-After

รอตาม retry_after แล้วค่อยส่งใหม่

9000400
PAYMENT_EXISTS
มีการชำระเงินนี้อยู่แล้ว

สร้าง invoice ด้วย order_id ที่เคยใช้แล้ว

ใช้ order_id ใหม่ทุกครั้ง

9002400
PAYMENT_NOT_FOUNDVerified
ไม่พบการชำระเงิน

ID ที่ระบุไม่มีในระบบ (สำหรับ /v1/payment/info, /v1/payment/cancel) — ตอบ 400 ไม่ใช่ 404

ตรวจ payment id ว่าถูกต้องและอยู่ใน environment เดียวกัน

10000400
WITHDRAWAL_NOT_FOUNDVerified
ไม่พบการถอนเงิน

id หรือ order_id ของ withdrawal ไม่มีในระบบ — ตอบ 400 ไม่ใช่ 404

เช็ค id/order_id หรือเรียก /v1/withdrawal/list เพื่อหา

10002400
WITHDRAWAL_INVALID_ADDRESS
ที่อยู่สำหรับถอนไม่ถูกต้อง

withdrawal_address ว่าง หรือเลขพร้อมเพย์ไม่ตรงกับ promptpay_id_type — detail บอกสาเหตุ

ตรวจเลขบัญชีหรือเลขพร้อมเพย์และชนิดที่ส่งมา

10005400
WITHDRAWAL_ORDER_ID_EXISTS
order_id ของรายการถอนซ้ำ

มีรายการถอนที่ใช้ order_id นี้แล้ว

ใช้ order_id ใหม่ทุกครั้ง

10046400
WITHDRAWAL_DUPLICATE_ORDER_ID
order_id ซ้ำ (ส่งพร้อมกัน)

ส่ง order_id เดียวกันพร้อมกันสองครั้ง ตัวที่สองจะได้ code นี้

ตรวจด้วย /v1/withdrawal/info?order_id=... ว่าตัวแรกสร้างสำเร็จแล้วหรือยัง

10067400
WITHDRAWAL_AMOUNT_NOT_ROUND
ยอดถอนต้องเป็นจำนวนเต็มร้อย

ยอดถอน THB ไม่ใช่จำนวนเต็มร้อย เช่น 567 หรือ 1105

ปัดยอดเป็นจำนวนเต็มร้อยก่อนส่ง เช่น 500 หรือ 1100

38045409
P2P_DUPLICATE_ORDER_ID
order_id ซ้ำ

order_id นี้มี P2P session ที่ยังไม่หมดอายุอยู่แล้ว

ใช้ order_id ใหม่ หรือรอให้ session เดิมหมดอายุ

1002500
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;