รวม Error Code ของ EasySlip API ฉบับเข้าใจง่าย พร้อมวิธีแก้ปัญหาทีละเคส

การเชื่อมต่อ EasySlip API เข้ากับระบบร้านค้า เว็บไซต์ หรือแพลตฟอร์มต่าง ๆ ช่วยให้สามารถตรวจสอบสลิปและจัดการข้อมูลการชำระเงินแบบอัตโนมัติได้ แต่ในการใช้งานจริงอาจเจอ Error Code ที่ทำให้ตรวจสลิปไม่สำเร็จ แล้วแต่ละ Error หมายถึงอะไร และต้องแก้ตรงไหน? บทความนี้รวบรวม Error Code ของ EasySlip API v2 ตามเอกสารอย่างเป็นทางการ พร้อมอธิบายสาเหตุและแนวทางแก้ไขแบบเข้าใจง่าย เพื่อช่วยให้นักพัฒนาหรือทีมดูแลระบบหาเหตุของปัญหาได้เร็วขึ้น

EasySlip API Error Code คืออะไร?

เมื่อเรียก EasySlip API แล้วเกิดข้อผิดพลาด ระบบจะส่ง Response กลับมาเพื่อบอกว่า Request ไม่สำเร็จ โดยใน Error Response จะมีข้อมูลสำคัญ เช่น success, error.code และ error.message

ตัวอย่างโครงสร้าง Response:

{

  “success”: false,

  “error”: {

    “code”: “SLIP_NOT_FOUND”,

    “message”: “The slip could not be found or is invalid”

  }

}

ดังนั้นเวลาระบบเกิดปัญหา ไม่ควรดูแค่ HTTP Status Code แต่ควรตรวจสอบ error.code ด้วย เพราะรหัสนี้ช่วยระบุสาเหตุของปัญหาได้ละเอียดกว่า

รวม Error Code EasySlip API ที่พบบ่อย พร้อมวิธีแก้

1. Error 401: Authentication มีปัญหา

กลุ่ม 401 เกี่ยวข้องกับการยืนยันตัวตน เช่น API Key, Header, Timestamp, Nonce หรือ Signature

MISSING_API_KEY / INVALID_API_KEY

หากไม่มี API Key หรือ API Key ไม่ถูกต้อง ระบบจะตอบกลับ 401

วิธีแก้คือเช็ก API Key และ Header ที่ส่งไปกับ Request ให้ถูกต้อง โดย API v2 ใช้ Authentication ตามรูปแบบที่กำหนดในเอกสาร EasySlip สำหรับการเชื่อมต่อแบบ Partners API ยังมี Error ที่เกี่ยวข้องกับ Authentication เช่น INVALID_AUTH_HEADERS, MISSING_BRANCH_KEY, INVALID_BRANCH_KEY, INVALID_TIMESTAMP, DUPLICATE_NONCE และ INVALID_SIGNATURE

INVALID_SIGNATURE

เกิดเมื่อ Signature ที่ส่งไปไม่ตรงกับที่ระบบคำนวณ กรณีนี้ควรตรวจสอบ Secret Key รวมถึงขั้นตอนการสร้าง HMAC-SHA256 Signature โดยเฉพาะ HTTP Method, Path, Timestamp, Nonce และ Body Hash ที่ใช้ในการสร้าง Signature

INVALID_TIMESTAMP

Timestamp ที่ส่งมานอกช่วงเวลาที่ระบบยอมรับ อาจเกิดจากเวลาบน Server ไม่ตรงกับเวลาปัจจุบัน ควรตรวจสอบ System Clock ของ Server และการสร้าง Unix Timestamp โดยเอกสาร Authentication ระบุช่วงที่ยอมรับไว้ที่ประมาณ ±5 นาที

DUPLICATE_NONCE

หมายถึง Nonce ถูกใช้ซ้ำ ซึ่งไม่ควรเกิดขึ้นกับแต่ละ Request วิธีแก้คือสร้าง UUID ใหม่สำหรับทุก Request

2. Error 403: ไม่มีสิทธิ์หรือโควต้าไม่เพียงพอ

IP_NOT_ALLOWED

หากระบบเปิดใช้ IP Whitelist แต่ IP ของ Server ที่ส่ง Request ไม่อยู่ในรายการที่อนุญาต ระบบจะปฏิเสธ Request วิธีแก้คือเพิ่ม IP ของ Server เข้าไปใน Whitelist ตามการตั้งค่าของระบบ

QUOTA_EXCEEDED

Error นี้หมายถึงใช้งาน API ถึงโควต้าที่กำหนดแล้ว แนวทางแก้คือเพิ่มหรือเปลี่ยนแผนบริการตามความเหมาะสม หรือรอให้โควต้ากลับมาใช้งานได้ตามรอบที่กำหนด โดย EasySlip มีข้อมูลสำหรับตรวจสอบการใช้งานโควต้าในระบบ สำหรับระบบที่มีหลาย Branch ควรระวังเรื่อง Branch Quota ด้วย เพราะ EasySlip รองรับการติดตามโควต้าแยกตาม Branch

BRANCH_INACTIVE

หมายถึง Branch ที่กำลังเรียกใช้งานถูกปิดใช้งาน วิธีแก้คือตรวจสอบสถานะ Branch และเปิดใช้งานอีกครั้งผ่าน Developer Portal หากมีสิทธิ์ดำเนินการ

3. Error 400: Request หรือรูปภาพไม่ถูกต้อง

VALIDATION_ERROR

เกิดจากข้อมูลใน Request ไม่ตรงตามรูปแบบที่ API กำหนด ควรตรวจสอบ Request Body, Parameter และข้อมูลที่ส่งเข้า Endpoint ว่าครบและถูกต้องหรือไม่

URL_PROTOCOL_NOT_ALLOWED

หากส่ง URL รูปภาพเข้า API ระบบรองรับเฉพาะ HTTP และ HTTPS ดังนั้น URL ที่ใช้ต้องเป็น URL ที่สามารถเข้าถึงได้ผ่าน Protocol ที่รองรับ

URL_INVALID_IP_RANGE

เกิดเมื่อ URL ชี้ไปยัง IP Range ที่ระบบไม่อนุญาต เช่น Private หรือ Internal IP ควรเปลี่ยนเป็น URL ที่เข้าถึงได้จากภายนอกและไม่อยู่ใน Restricted IP Range

IMAGE_URL_UNREACHABLE

หมายถึง EasySlip ไม่สามารถเข้าถึง URL ของรูปภาพได้ ควรตรวจสอบว่า URL เปิดจากภายนอกได้จริง ไม่ต้อง Login และ Server ปลายทางไม่ได้ปิดกั้นการเข้าถึง

IMAGE_SIZE_TOO_LARGE

ไฟล์รูปภาพมีขนาดเกินข้อกำหนด โดยเอกสารระบุขนาดสูงสุด 4 MB วิธีแก้คือ Compress หรือปรับขนาดรูปก่อนส่งเข้า API

INVALID_IMAGE_TYPE / INVALID_IMAGE_FORMAT

หมายถึง URL หรือไฟล์ที่ส่งเข้าไปไม่ใช่รูปภาพที่ระบบรองรับ หรือรูปภาพมี Format ไม่ถูกต้อง นอกจากนี้ระบบของ EasySlip Format ที่รองรับ ได้แก่ JPEG, PNG, GIF และ WebP เป็นต้น

4. Error 404: ไม่พบสลิปหรือ Resource

SLIP_NOT_FOUND

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

SLIP_PENDING

สำหรับสลิปธนาคารกรุงเทพ หากรายการยังอยู่ในสถานะ Pending ระบบอาจตอบกลับด้วย SLIP_PENDING วิธีรับมือคือรอสักครู่แล้วลองตรวจสอบใหม่ตามที่เอกสารแนะนำ

NOT_FOUND

หมายถึง Resource หรือ Endpoint ที่เรียกไม่พบ ควรตรวจสอบ URL, Endpoint และ Path ที่ใช้ใน Request ว่าถูกต้องหรือไม่

5. Error 429: เรียก API มากเกิน Rate Limit

RATE_LIMIT_EXCEEDED

Error 429 เกิดเมื่อส่ง Request เกินจำนวนที่ระบบอนุญาตต่อวินาที เพราะ Verify Endpoint มีการกำหนด Rate Limit ตาม Transactions Per Second (TPS) และ Response จะมี Header เช่น X-RateLimit-Limit, X-RateLimit-Remaining และ X-RateLimit-Reset เพื่อช่วยติดตามการใช้งาน เมื่อเจอ 429 ควรอ่านค่า Retry-After แล้วรอก่อนส่ง Request ใหม่ แทนการยิง API ซ้ำทันที

6. Error 500: ปัญหาฝั่ง Server

API_SERVER_ERROR

หมายถึงเกิดปัญหากับ Service หรือระบบ Backend ที่เกี่ยวข้อง กรณีนี้ควร Retry โดยกำหนดจำนวนครั้งและระยะห่างระหว่างแต่ละ Request อย่างเหมาะสม EasySlip เองมีตัวอย่างการใช้ Retry และ Backoff สำหรับ Error ประเภทนี้

INTERNAL_SERVER_ERROR

เป็น Internal Server Error ที่เกิดจากปัญหาภายในระบบ หากเกิดซ้ำอย่างต่อเนื่อง ควรเก็บ Error Code, Message, เวลาเกิดปัญหา และข้อมูลที่จำเป็นสำหรับ Debug ก่อนติดต่อทีม Support

วิธีออกแบบระบบให้รับมือ EasySlip API Error ได้ดีขึ้น

การเช็ก Error Code อย่างเดียวอาจไม่พอ หากระบบถูกใช้งานจริงในธุรกิจ ควรออกแบบ Error Handling ตั้งแต่ต้น

แยก Error ที่ Retry ได้กับ Retry ไม่ได้

ตัวอย่างเช่น API_SERVER_ERROR สามารถนำไปทำ Retry ได้ ขณะที่ INVALID_API_KEY, SLIP_NOT_FOUND หรือ VALIDATION_ERROR ควรแก้สาเหตุก่อน ไม่ควรยิงซ้ำแบบไม่มีเงื่อนไข

เก็บ Log ทุกครั้งที่ API Error

อย่างน้อยควรเก็บ

• Error Code
• Error Message
• HTTP Status
• เวลาเกิด Error
• Endpoint
• Request ID หรือข้อมูลสำหรับติดตามรายการที่เหมาะสม
• จำนวนครั้งที่ Retry

ข้อมูลเหล่านี้ช่วยให้ทีมพัฒนาหาสาเหตุได้เร็วขึ้น และ EasySlip ก็แนะนำแนวทาง Logging เพื่อช่วย Debug เช่นกัน

อย่า Retry ทุก Error

การ Retry ควรมีเงื่อนไข ไม่ใช่เมื่อเจอ Error อะไรก็ยิง Request ใหม่ทันที เพราะบาง Error เป็นปัญหาจากข้อมูลหรือ Authentication ซึ่ง Retry ก็ไม่ช่วยแก้ปัญหา

สรุป EasySlip API Error Code

การเจอ Error จาก EasySlip API ไม่ได้หมายความว่า API ล่มเสมอไป แต่ต้องดูทั้ง HTTP Status และ error.code เพื่อหาสาเหตุที่แท้จริง จำง่าย ๆ คือ

• 400 → ตรวจ Request และข้อมูลที่ส่ง
• 401 → ตรวจ Authentication, API Key และ Signature
• 403 → ตรวจ Permission, IP และ Quota
• 404 → ตรวจ Resource หรือข้อมูลสลิป
• 429 → ลดความถี่ Request และทำตาม Retry-After
• 500 → ตรวจสอบปัญหาฝั่ง Server และ Retry อย่างเหมาะสม

การออกแบบระบบให้รู้จัก Error แต่ละประเภทตั้งแต่แรก จะช่วยให้ระบบตรวจสอบสลิปทำงานได้เสถียรมากขึ้น และลดเวลาที่ทีมต้องไล่ Debug เมื่อเกิดปัญหา

คำถามที่พบบ่อย (FAQ)

EasySlip API ขึ้น SLIP_NOT_FOUND หมายความว่าสลิปปลอมหรือไม่?

ไม่ควรสรุปทันทีว่าเป็นสลิปปลอม เพราะ SLIP_NOT_FOUND หมายถึงระบบไม่พบสลิปหรือสลิปไม่ถูกต้อง และเอกสารยังระบุว่าสลิปที่เก่าเกินระยะเวลาที่รองรับอาจได้รับ Error Code นี้เช่นกัน

EasySlip API ขึ้น 401 ต้องแก้อย่างไร?

ให้ตรวจสอบ Authentication เช่น API Key, Header, Timestamp, Nonce และ Signature ตามรูปแบบ API ที่ใช้งาน หากเป็น Partners API ยังต้องตรวจสอบ Branch Key และ HMAC-SHA256 Signature ด้วย

EasySlip API ขึ้น 429 ทำอย่างไร?

หมายถึงส่ง Request เกิน Rate Limit ควรอ่านค่า Retry-After จาก Response แล้วรอก่อน Retry และควรออกแบบระบบให้ควบคุมจำนวน Request ไม่ให้เกิน Rate Limit

ถ้า EasySlip API ขึ้น 500 ควร Retry หรือไม่?

ควร Retry อย่างมีเงื่อนไข โดยกำหนดจำนวนครั้งและระยะห่างระหว่าง Request ไม่ควรยิงซ้ำแบบต่อเนื่อง และหากยังเกิดปัญหาควรเก็บ Log เพื่อใช้ตรวจสอบเพิ่มเติม

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