รหัส Error

รายการรหัส Error ทั้งหมดที่ EasySlip API ส่งกลับมา

เช็คด้วย error.code ไม่ใช่ข้อความ

สำหรับ v2 ให้ใช้ error.code (เช่น SLIP_NOT_FOUND) เป็น contract ที่คงที่ — เขียน logic ให้ match กับค่านี้ ส่วน error.message เป็นข้อความสำหรับให้คนอ่านและอาจเปลี่ยนได้โดยไม่แจ้งล่วงหน้า คอลัมน์ คำอธิบาย ด้านล่างเป็นคำอธิบายของแต่ละรหัส ไม่ใช่ error.message จริงที่ API ส่งกลับมา (สำหรับ v1 ฟิลด์ message จะเป็นตัวรหัสเอง)

รหัส Error ของ API v2

Error การยืนยันตัวตน (401)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
MISSING_API_KEY	Authorization header is required	ไม่มี Authorization header	เพิ่ม header Authorization: Bearer YOUR_API_KEY
INVALID_API_KEY	The provided API key is invalid	API Key ไม่มีอยู่หรือรูปแบบผิด	ตรวจสอบ API Key ให้ถูกต้อง

Error สิทธิ์การเข้าถึง (403)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
BRANCH_INACTIVE	This API branch has been deactivated	Branch ถูกปิดใช้งาน	เปิดใช้งานใหม่ใน Developer Portal
SERVICE_BANNED	Service has been banned	ละเมิดเงื่อนไขการใช้งาน	ติดต่อฝ่ายสนับสนุน
SERVICE_EXPIRED	Service has expired	แพ็กเกจ/สมาชิกหมดอายุ	ต่ออายุแพ็กเกจ
IP_NOT_ALLOWED	Your IP address is not in the allowed list	IP ไม่อยู่ใน Whitelist	เพิ่ม IP เข้า Whitelist
QUOTA_EXCEEDED	Your API quota has been exceeded	ใช้โควต้ารายเดือนหมด	อัปเกรดแพ็กเกจหรือรอรีเซ็ต
USER_BANNED	User has been banned	บัญชีผู้ใช้ละเมิดเงื่อนไข	ติดต่อฝ่ายสนับสนุน

Error การตรวจสอบข้อมูล (400)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
VALIDATION_ERROR	Validation failed	Request Body ไม่ถูกต้อง	ตรวจสอบรูปแบบ Request
URL_PROTOCOL_NOT_ALLOWED	Only HTTP/HTTPS allowed	URL ไม่ใช่ HTTP	ใช้ URL แบบ HTTP หรือ HTTPS
URL_INVALID_IP_RANGE	URL points to restricted IP	IP ภายใน/ส่วนตัว	ใช้ URL สาธารณะ
IMAGE_URL_UNREACHABLE	Unable to access URL	เข้าถึง URL ไม่ได้	ตรวจสอบว่า URL เข้าถึงได้จากภายนอก
IMAGE_SIZE_TOO_LARGE	Image exceeds 4MB limit	ไฟล์ใหญ่เกินไป	ลดขนาดรูปภาพ
INVALID_IMAGE_FORMAT	File is not a valid image	ไฟล์เสียหรือรูปแบบผิด	ใช้ JPEG, PNG, GIF, WebP
INVALID_BANK_CODE	The provided bankCode is not supported	bankCode ไม่อยู่ในรายชื่อธนาคาร	ใช้รหัสจาก GET /banks
INVALID_EXTRA_VERIFY	extraVerify is not valid for this bank	ค่าที่ส่งมาไม่อยู่ในรายการตัวเลือกของธนาคาร	ใช้ค่า extraVerify ของธนาคารจาก GET /banks
INVALID_EXTRA_VERIFY	extraVerify is required for this bank	ธนาคารต้องการตัวเลือกแต่ไม่ได้ส่งมา (เช่น ตอนเปลี่ยน bankCode)	ส่งค่า extraVerify ที่ถูกต้องจาก GET /banks

Error ไม่พบข้อมูล (404)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
SLIP_NOT_FOUND	Slip not found or invalid	สลิปไม่ถูกต้องหรือไม่มี QR	ตรวจสอบความถูกต้องของสลิป
SLIP_PENDING	Bangkok Bank slip is pending	สลิปโอนภายใน 5 นาที	รอสักครู่แล้วลองใหม่
BANK_ACCOUNT_NOT_FOUND	Bank account not found	ไม่พบบัญชี หรือบัญชีไม่ได้เชื่อมโยงกับ Branch ของคุณ	ตรวจสอบ id บัญชีและการเชื่อมโยง Branch
NOT_FOUND	Resource not found	Endpoint ผิด	ตรวจสอบ URL ของ Endpoint

Error ข้อมูลซ้ำ (409)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
BANK_ACCOUNT_DUPLICATE	An active account with the same bank code and number already exists	bankCode + bankNumber ซ้ำใน Service ของคุณ	ใช้บัญชีเดิมหรือใช้ข้อมูลอื่น

Error เกิน Rate Limit (429)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
RATE_LIMIT_EXCEEDED	Too many requests	เรียกตรวจสอบสลิปถี่เกินไป	รอตามจำนวนวินาทีใน Retry-After แล้วลองใหม่ — ดู Rate Limits

Error ของเซิร์ฟเวอร์ (500)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
API_SERVER_ERROR	Service temporarily unavailable	ข้อผิดพลาดชั่วคราวในการประมวลผล	ลองใหม่ภายหลัง
INTERNAL_SERVER_ERROR	Internal server error	ข้อผิดพลาดที่ไม่คาดคิด	ติดต่อฝ่ายสนับสนุน

รหัส Error ของ API v1

Error การยืนยันตัวตน (401)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
unauthorized	Unauthorized	API Key ไม่ถูกต้องหรือไม่มี	ตรวจสอบ Authorization header

Error สิทธิ์การเข้าถึง (403)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
access_denied	Access denied	IP ไม่อยู่ใน Whitelist	เพิ่ม IP เข้า Whitelist
application_expired	Application expired	สมาชิกหมดอายุ	ต่ออายุสมาชิก
application_deactivated	Application deactivated	แอปถูกปิดใช้งาน	เปิดใช้งานใหม่ใน Portal
quota_exceeded	Quota exceeded	ใช้โควต้ารายเดือนหมด	อัปเกรดแพ็กเกจ

Error การตรวจสอบข้อมูล (400)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
invalid_payload	Invalid payload	Payload QR ผิดรูปแบบ	ตรวจสอบรูปแบบ Payload
invalid_check_duplicate	Invalid checkDuplicate	รูปแบบ boolean ผิด	ใช้ true หรือ false
invalid_url	Invalid URL	URL ผิดรูปแบบหรือไม่ปลอดภัย	ตรวจสอบรูปแบบ URL
invalid_image	Invalid image	ไม่ใช่รูปภาพที่ถูกต้อง	ใช้รูปแบบที่รองรับ
image_size_too_large	Image too large	เกิน 4MB	ลดขนาดรูปภาพ
invalid_request	Invalid request	Schema ไม่ผ่านการตรวจสอบ	ตรวจสอบ Request Body
duplicate_slip	Duplicate slip	ตรวจสอบไปแล้ว	ดูรายละเอียดใน data

Error ไม่พบข้อมูล (404)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
slip_not_found	Slip not found	สลิปไม่ถูกต้องหรือปลอม	ตรวจสอบความถูกต้องของสลิป
slip_pending	Bangkok Bank slip is pending	สลิปโอนภายใน 5 นาที	รอสักครู่แล้วลองใหม่
qrcode_not_found	QR code not found	ไม่มี QR ในรูป	ใช้รูปที่ชัดเจนขึ้น
not_found	Not found	Endpoint ผิด	ตรวจสอบ URL

Error เกิน Rate Limit (429)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
rate_limit_exceeded	Too many requests	เรียกตรวจสอบสลิปถี่เกินไป	รอตามจำนวนวินาทีใน Retry-After แล้วลองใหม่ — ดู Rate Limits

Error ของเซิร์ฟเวอร์ (500)

รหัส	คำอธิบาย	สาเหตุ	วิธีแก้ไข
server_error	Server error	ข้อผิดพลาดภายใน	ลองใหม่ภายหลัง
api_server_error	Service temporarily unavailable	ข้อผิดพลาดชั่วคราวในการประมวลผล	ลองใหม่ภายหลัง

รูปแบบ Error Response

API v2

{
  "success": false,
  "error": {
    "code": "SLIP_NOT_FOUND",
    "message": "The slip could not be found or is invalid"
  }
}

ข้อความของ VALIDATION_ERROR

สำหรับ VALIDATION_ERROR ค่า message จะบอกว่าฟิลด์ไหนไม่ผ่านและเพราะอะไร เช่น "bankNumber: Too small: expected string to have >=1 characters" หากมีหลายฟิลด์ที่ไม่ผ่าน จะถูกรวมเป็นข้อความเดียวคั่นด้วย ; ทั้งนี้ code จะเป็น VALIDATION_ERROR เสมอ (ไม่มีฟิลด์ details แยกต่างหาก — ให้ match ที่ code แล้วแสดง message ให้ผู้ใช้)

API v1

{
  "status": 404,
  "message": "slip_not_found"
}

สลิปซ้ำ (v1)

ส่งข้อมูลสลิปกลับมาพร้อมกับ Error:

{
  "status": 400,
  "message": "duplicate_slip",
  "data": {
    "payload": "...",
    "transRef": "...",
    "amount": { ... }
  }
}

แนวทางการจัดการ Error ที่ดี

1. ตรวจสอบ Success/Status ก่อน

// v2
if (!result.success) {
  console.error(`Error [${result.error.code}]: ${result.error.message}`);
}

// v1
if (result.status !== 200) {
  console.error(`Error: ${result.message}`);
}

2. จัดการ Error เฉพาะกรณี

switch (result.error.code) {
  case 'QUOTA_EXCEEDED':
    // แจ้งเตือนผู้ใช้หรือหยุดการทำงานชั่วคราว
    break;
  case 'SLIP_NOT_FOUND':
    // ให้ผู้ใช้ลองใหม่
    break;
  case 'API_SERVER_ERROR':
    // ลองใหม่แบบ exponential backoff
    break;
}

3. ใส่ Retry Logic

async function verifyWithRetry(payload, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const result = await verify(payload);

    if (result.success) return result;

    if (result.error.code === 'API_SERVER_ERROR') {
      await sleep(1000 * (i + 1)); // Exponential backoff
      continue;
    }

    throw new Error(result.error.message);
  }
}

4. บันทึก Error เพื่อ Debug

if (!result.success) {
  console.error({
    timestamp: new Date().toISOString(),
    errorCode: result.error.code,
    errorMessage: result.error.message,
    payload: payload.substring(0, 20) + '...'
  });
}

ที่เกี่ยวข้อง

• Rate Limits
• รหัสธนาคาร
• ระยะเวลารองรับสลิป