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

โครงสร้าง

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_below_minimum",
    "message": "The amount is below the minimum of 100.",
    "param": "amount"
  },
  "requestId": "req_Z3k9QmP2xR7tLw4NbV8cYh1s"
}

ฟิลด์	คำอธิบาย
type	กลุ่มของ error (ตารางถัดไป)
code	รหัสที่ใช้เขียนเงื่อนไขในโค้ด ค่าคงที่
message	ข้อความสำหรับคนอ่าน อาจเปลี่ยนได้ ห้ามใช้เป็นเงื่อนไข
param	ชื่อฟิลด์หรือ header ที่เป็นปัญหา (ถ้ามี)
requestId	ค่าเดียวกับ header X-Request-Id แจ้งค่านี้เมื่อติดต่อซัพพอร์ต

500 internal_error ไม่มีรายละเอียดภายในระบบ ให้แจ้ง requestId แก่ทีมงาน

สำหรับฟิลด์ย่อย param จะเป็น path เช่น payer.accountNumber

คำเตือน (warnings)

response ที่สำเร็จอาจมี warnings เป็น array อยู่คู่กับ data คำเตือนไม่เปลี่ยนผลของคำขอ ให้บันทึกไว้และจัดการตามที่เห็นควร แต่ละรายการมีฟิลด์ code, message และ param แบบเดียวกับข้อผิดพลาด แต่ไม่มี type และ warnings จะมีเฉพาะเมื่อมีคำเตือนอย่างน้อยหนึ่งรายการ

{
  "data": { "object": "payin", "id": "pin_...", "...": "..." },
  "warnings": [
    {
      "code": "payer_name_differs",
      "message": "An existing payer with this bank account was used. Its stored account name differs from the one sent and was kept; it is used for payment matching.",
      "param": "payer.accountName"
    }
  ],
  "requestId": "req_..."
}

code	มาจาก	ความหมาย
payer_name_differs	POST /v1/payins, POST /v1/payouts ที่ส่ง payer แบบ inline	ใช้ payer เดิมที่ธนาคารและเลขบัญชีตรงกัน แต่ชื่อที่บันทึกไว้ (param: payer.accountName) หรือชื่อภาษาอังกฤษ (payer.accountNameEn) ต่างจากที่ส่งมา ระบบคงชื่อเดิมไว้เพราะใช้จับคู่การโอน ถ้าต้องการเปลี่ยนให้ใช้ PATCH /v1/payers/{id}

ประเภท

type	HTTP	ความหมาย
invalid_request_error	400, 404, 409, 422	คำขอไม่ถูกต้อง หรือขัดกับสถานะหรือกฎของระบบ
authentication_error	401	การยืนยันตัวตนหรือการเซ็นไม่ผ่าน
permission_error	403	ยืนยันตัวตนผ่าน แต่ไม่มีสิทธิ์ทำรายการนี้
rate_limit_error	429	เกินโควตา
api_error	500	ข้อผิดพลาดฝั่งระบบ

ควรลองใหม่หรือไม่

กรณี	สิ่งที่ควรทำ
500, timeout หรือเชื่อมต่อไม่ได้	ลองใหม่แบบ backoff (เช่น 1, 2, 4, 8 วินาที) โดยเซ็นใหม่ทุกครั้ง
429 quota_exceeded	หยุดสักพักแล้วค่อยลอง หรือติดต่อทีมงาน
422 not_available_now, maintenance, no_collection_account_available, no_payout_account_available, slip_verification_unavailable	ลองใหม่ภายหลัง
400, 401, 403, 404, 409 และ 422 อื่นๆ	อย่าลองซ้ำด้วยข้อมูลเดิม แก้คำขอหรือสถานะก่อน

ส่งคำขอสร้างรายการซ้ำอย่างปลอดภัย

ถ้า POST /v1/payins, POST /v1/payouts หรือ POST /v1/withdrawals timeout คุณจะไม่รู้ว่ารายการถูกสร้างแล้วหรือยัง ให้ส่ง header Idempotency-Key กับคำขอสร้างทุกครั้ง แล้วส่งซ้ำได้เลย

Idempotency-Key: 6f1c2e8a-3b7d-4c0e-9a51-2d8f4b7e1c30

• ใช้ key ใหม่ที่ไม่ซ้ำ (เช่น UUID) ต่อหนึ่งรายการ และใช้ key เดิม เมื่อส่งรายการนั้นซ้ำ key ยาว 8-255 ตัว ประกอบด้วย A-Z a-z 0-9 _ - : .
• ส่งซ้ำด้วย key เดิมและคำขอเดิมภายใน 24 ชั่วโมง จะได้ response เดิมพร้อม header Idempotent-Replayed: true โดยไม่สร้างรายการใหม่
• ใช้ key เดิมกับคำขอที่ต่างไป (body หรือ query string ไม่เหมือนเดิม) จะได้ 422 idempotency_key_reused
• ถ้าคำขอแรกยังทำงานไม่เสร็จ คำขอที่ส่งซ้ำจะได้ 409 idempotency_request_in_progress ให้รอสักครู่แล้วลองใหม่
• ถ้าคำขอแรกจบด้วยข้อผิดพลาด key จะถูกปล่อย และคำขอที่ส่งซ้ำจะทำงานเหมือนคำขอใหม่

header นี้ไม่บังคับ ถ้าไม่ส่ง ให้ค้นด้วย reference ก่อนส่งซ้ำ เช่น GET /v1/payouts?reference=withdraw-20001 และตั้ง reference ให้ไม่ซ้ำทุกครั้ง

รหัสทั้งหมด

400 คำขอไม่ถูกต้อง

code	ความหมาย
invalid_request	คำขอไม่ถูกต้อง เช่น JSON อ่านไม่ได้
parameter_invalid	ค่าของพารามิเตอร์ไม่ถูกต้อง ดู param
parameter_missing	ขาดพารามิเตอร์ที่จำเป็น ดู param
parameter_unknown	มีพารามิเตอร์ที่ไม่รู้จัก (ใน body, query หรือ part ของ multipart)
parameters_exclusive	ส่งพารามิเตอร์ที่ใช้ร่วมกันไม่ได้มาพร้อมกัน เช่น payerId กับ payer โดย param ระบุตัวที่สอง
invalid_cursor	cursor ไม่ถูกต้อง
date_range_too_large	ช่วงวันที่เกิน 31 วัน
invalid_webhook_url	webhookUrl ไม่ถูกต้องหรือไม่มี
invalid_return_url	returnUrl ไม่ถูกต้อง
unsupported_currency	สกุลเงินไม่รองรับ
unsupported_method	ช่องทางชำระเงินไม่รองรับ
file_invalid	ไม่มีไฟล์ หรือไม่ใช่ JPG/PNG ขนาดไม่เกิน 5 MB

401 การยืนยันตัวตน

code	ความหมาย
authentication_required	ขาด header ที่จำเป็น param บอกชื่อ header
invalid_api_key	API key ไม่ถูกต้อง หรือใช้ test key ตอนบัญชีไม่ได้อยู่ในโหมดทดสอบ
invalid_timestamp	X-Timestamp ไม่ใช่วินาที หรือห่างจากเวลาเซิร์ฟเวอร์เกิน 300 วินาที
invalid_nonce	X-Nonce ต้องยาว 16-128 ตัวของ A-Z a-z 0-9 _ -
nonce_reused	nonce นี้ถูกใช้ไปแล้ว
invalid_signature	ลายเซ็นไม่ถูกต้อง ดูข้อผิดพลาดที่พบบ่อย

403 สิทธิ์

code	ความหมาย
partner_inactive	บัญชีพาร์ทเนอร์ไม่ active
ip_not_allowed	IP นี้ไม่อยู่ใน allow-list
payins_disabled	บัญชีนี้ปิดการรับเงิน
payouts_disabled	บัญชีนี้ปิดการจ่ายเงิน

404 ไม่พบ

code	ความหมาย
resource_not_found	ไม่พบข้อมูล หรือไม่ใช่ของบัญชีคุณ หรือ ID ผิดรูปแบบ
route_not_found	ไม่มี endpoint นี้ ตรวจ method และ path
payer_not_found	ไม่พบ payerId ที่ส่งมาใน body

409 ขัดกับสถานะปัจจุบัน

code	ความหมาย
pending_payin_exists	payer มี pay-in ที่รอจ่ายอยู่แล้ว
pending_payout_exists	payer มี payout ที่ยังไม่จบอยู่แล้ว
pending_withdrawal_exists	มีคำขอถอนเงินที่กำลังดำเนินการ
payin_not_cancelable	pay-in ยกเลิกไม่ได้ในสถานะนี้
payout_not_cancelable	payout ยกเลิกไม่ได้ในสถานะนี้
payin_not_pending	pay-in ไม่ได้รอการจ่ายแล้ว
payer_has_payments	payer มีรายการแล้ว ลบไม่ได้
slip_duplicate	สลิปนี้ถูกใช้แล้ว
idempotency_request_in_progress	คำขอที่ใช้ Idempotency-Key นี้ยังทำงานไม่เสร็จ รอสักครู่แล้วลองใหม่
conflict	คำขอขัดกับสถานะปัจจุบันของข้อมูล

422 ถูกปฏิเสธตามกฎของระบบ

code	ความหมาย
amount_invalid	ยอดไม่ถูกต้อง
amount_below_minimum	ยอดต่ำกว่าขั้นต่ำ ข้อความระบุค่าขั้นต่ำ
amount_above_maximum	ยอดสูงกว่าขั้นสูง ข้อความระบุค่าขั้นสูง
amount_below_fee	ยอดต่ำกว่าค่าธรรมเนียมรวม
insufficient_balance	ยอดคงเหลือที่ใช้ได้ไม่พอ
daily_limit_exceeded	เกินวงเงินถอนต่อวัน
no_collection_account_available	ไม่มีบัญชีรับเงินว่าง
no_payout_account_available	ไม่มีบัญชีจ่ายเงินว่าง
not_available_now	อยู่นอกเวลาให้บริการ
maintenance	ระบบปิดปรับปรุง
payer_inactive	payer ถูกปิด (inactive)
payer_blocked	payer ถูกระงับ
bank_not_found	ไม่พบ bankCode
referral_code_not_found	ไม่พบรหัสผู้แนะนำ
referrer_inactive	ผู้แนะนำถูกปิด
slip_unreadable	อ่าน QR code บนสลิปไม่ได้
slip_verification_failed	ตรวจสลิปไม่ผ่าน
slip_amount_mismatch	ยอดในสลิปไม่ตรงกับ pay-in
slip_receiver_mismatch	ผู้รับในสลิปไม่ตรงกับ pay-in
slip_verification_unavailable	บริการตรวจสลิปใช้ไม่ได้ชั่วคราว
request_unprocessable	ดำเนินการตามคำขอไม่ได้ แจ้ง requestId แก่ทีมงาน
idempotency_key_reused	Idempotency-Key นี้เคยใช้กับคำขออื่นแล้ว

429 และ 500

HTTP	code	ความหมาย
429	quota_exceeded	เกินโควตาการใช้งาน
500	internal_error	ข้อผิดพลาดภายใน แจ้ง requestId แก่ทีมงาน