03.09 Error Handling & Business Error Codes

---

📌 At a Glance

รายการ	รายละเอียด
Topic	Error Handling & Business Error Codes
Difficulty	⭐⭐ Intermediate
Reading Time	8 นาที
Target	Developer

---

🎯 Learning Objectives

หลังจากศึกษาหัวข้อนี้แล้ว ผู้อ่านจะสามารถ

• เข้าใจรูปแบบ Error Response ของ SISAHYGO API
• เข้าใจ Business Error Codes
• จัดการข้อผิดพลาดใน Client System ได้อย่างถูกต้อง

---

Overview

SISAHYGO API แยกการแจ้งข้อผิดพลาดออกเป็น 2 ระดับ

1. HTTP Status Code
2. Business Error Code

HTTP Status Code ใช้บอกผลของการสื่อสาร

Business Error Code ใช้ระบุสาเหตุของปัญหาในระดับธุรกิจ

การแยกสองส่วนนี้ทำให้ Client System สามารถวิเคราะห์ปัญหาได้ละเอียดและพัฒนา Error Handling ได้ง่าย

---

Figure 3-9 Error Handling Flow

(แทรกรูป Figure 3-9 : Error Handling Flow)

Figure 3-9 แสดงขั้นตอนการตรวจสอบ Request การตอบกลับ HTTP Status Code และ Business Error Code พร้อมแนวทางการจัดการข้อผิดพลาดใน Client System

---

Standard Error Response

{
    "success": false,
    "code": "ORD001",
    "message": "Duplicate Reference Number",
    "data": null,
    "timestamp": "2026-07-02T10:15:30+07:00",
    "version": "1.1"
}

---

Business Error Code Categories

Prefix	Description
AUTH	Authentication
ORD	Order Checking
PRD	Product
RCV	Receiver
SHP	Shipment
SYS	Internal System

---

Common Business Error Codes

Code	Description	Suggested Action
AUTH001	Invalid API Key	ตรวจสอบ API Key
AUTH002	Missing API Key	ส่ง Header X-API-Key
ORD001	Duplicate Reference Number	เปลี่ยนเลขอ้างอิง
ORD002	Order Not Found	ตรวจสอบ Reference Number
PRD001	Product Code Not Found	Synchronize Products
RCV001	Receiver Code Not Found	Synchronize Receivers
SHP001	Shipment Not Found	ตรวจสอบ Shipment Reference
SYS001	Internal Server Error	Retry หรือติดต่อ Support

---

Error Handling Flow

Client System ควรจัดการตามลำดับดังนี้

1. ตรวจสอบ HTTP Status Code
2. อ่านค่า success
3. อ่าน code
4. แสดง message
5. บันทึก Log

---

Key Points

Item	Recommendation
HTTP Status	ตรวจสอบก่อน
success	ต้องเป็น true
code	ใช้จัดการ Error
message	ใช้แสดงผล
data	จะเป็น null เมื่อ Error

---

Implementation Notes

• อย่าใช้ message เป็นเงื่อนไขใน Business Logic
• ใช้ code สำหรับเขียนโปรแกรม
• รองรับ Error Code ใหม่ในอนาคต
• บันทึก HTTP Status และ Business Error Code ทุกครั้งที่เกิดข้อผิดพลาด

---

Best Practices

• แยก Error Handling ตามประเภทของ Error
• Retry เฉพาะกรณีที่เหมาะสม เช่น SYS001
• แจ้งผู้ใช้งานเมื่อเกิด Validation Error
• เก็บ Log เพื่อช่วยวิเคราะห์ปัญหา

---

Summary

SISAHYGO API ใช้มาตรฐาน Error Handling ที่แยก HTTP Status Code ออกจาก Business Error Code เพื่อให้ Client System สามารถจัดการข้อผิดพลาดได้อย่างมีประสิทธิภาพและรองรับการขยายระบบในอนาคต

---

Next Step

➡️ 03.10 API Best Practices