09.03 Standard Error Response Format

---

📌 At a Glance

รายการ	รายละเอียด
Topic	Standard Error Response Format
Difficulty	⭐⭐ Beginner
Reading Time	10 นาที
Target	Developer, System Integrator
Related APIs	All APIs

---

🎯 Learning Objectives

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

• เข้าใจรูปแบบมาตรฐานของ Error Response
• แยกข้อมูล Error ที่สำคัญได้
• ออกแบบ Error Handling ใน Client System
• แสดงข้อความผิดพลาดแก่ผู้ใช้งานได้อย่างเหมาะสม

---

Overview

เมื่อการเรียก API ไม่สามารถดำเนินการได้สำเร็จ SISAHYGO จะตอบกลับด้วย HTTP Status Code ที่เหมาะสม พร้อม JSON Error Response

Client System ควรตรวจสอบ HTTP Status Code ก่อน จากนั้นจึงอ่านรายละเอียดของ Error Response เพื่อดำเนินการแก้ไข แจ้งผู้ใช้งาน หรือ Retry Request ตามประเภทของข้อผิดพลาด

เพื่อให้ทุก API มีพฤติกรรมที่สอดคล้องกัน SISAHYGO ใช้โครงสร้าง Error Response มาตรฐานเดียวกันสำหรับทุกบริการ

---

Figure 9-3 Standard Error Response

Figure 9-3 แสดงโครงสร้างมาตรฐานของ JSON Error Response ที่ใช้ร่วมกันในทุก API ของ SISAHYGO

---

Standard Error Response

ตัวอย่างโครงสร้างมาตรฐาน

{
    "success": false,
    "message": "Validation failed.",
    "error_code": "ERR-VAL-001",
    "details": [
        {
            "field": "customer_rec_id",
            "message": "The selected receiver does not exist."
        },
        {
            "field": "items.0.product_id",
            "message": "The selected product does not exist."
        }
    ],
    "timestamp": "2026-07-01T14:30:00+07:00",
    "path": "/api/v1/order-checkings"
}

---

Response Structure

Error Response

│

├── success

├── message

├── error_code

├── details[]

│      │

│      ├── field

│      └── message

├── timestamp

└── path

---

Root Fields

Field	Type	Description
success	Boolean	ผลลัพธ์ของคำขอ (false)
message	String	ข้อความสรุปของข้อผิดพลาด
error_code	String	รหัสข้อผิดพลาดสำหรับอ้างอิง
details	Array	รายละเอียดข้อผิดพลาดแต่ละรายการ
timestamp	DateTime	วันที่และเวลาที่เกิดข้อผิดพลาด
path	String	API Endpoint ที่เรียกใช้งาน

---

Details Object

Field	Type	Description
field	String	ชื่อ Field ที่เกิดข้อผิดพลาด
message	String	รายละเอียดของข้อผิดพลาด

---

Example : Validation Error

HTTP/1.1 422 Unprocessable Entity

{
    "success": false,
    "message": "Validation failed.",
    "error_code": "ERR-VAL-001",
    "details": [
        {
            "field": "amount",
            "message": "Amount must be greater than zero."
        }
    ]
}

---

Example : Authentication Error

HTTP/1.1 401 Unauthorized

{
    "success": false,
    "message": "Invalid API Key.",
    "error_code": "ERR-AUTH-001"
}

---

Example : Resource Not Found

HTTP/1.1 404 Not Found

{
    "success": false,
    "message": "Shipment not found.",
    "error_code": "ERR-NOTFOUND-001"
}

---

Error Code Convention

แนะนำให้ใช้รหัสข้อผิดพลาดตามหมวดหมู่

Prefix	Description
ERR-AUTH	Authentication
ERR-VAL	Validation
ERR-BUS	Business Rules
ERR-NOTFOUND	Resource Not Found
ERR-SERVER	Internal Server Error

ตัวอย่าง

Error Code	Description
ERR-AUTH-001	Invalid API Key
ERR-VAL-001	Validation Failed
ERR-BUS-001	Business Rule Violation
ERR-NOTFOUND-001	Resource Not Found
ERR-SERVER-001	Internal Server Error

---

Client Handling Flow

Receive Error Response

        │

        ▼

Check HTTP Status

        │

        ▼

Read message

        │

        ▼

Read error_code

        │

        ▼

Read details[]

        │

        ▼

Display Friendly Message

        │

        ▼

Retry or Correct Data

---

Implementation Notes

• ตรวจสอบ HTTP Status Code ก่อนเสมอ
• ใช้ error_code สำหรับการเขียนโปรแกรม ไม่ควรอ้างอิงจากข้อความ (message)
• แสดง message หรือข้อความที่แปลแล้วให้ผู้ใช้งาน
• ใช้ details เพื่อระบุ Field ที่ต้องแก้ไข

---

Best Practices

• อย่าแสดง Stack Trace หรือข้อมูลภายในระบบแก่ผู้ใช้งาน
• บันทึก error_code และ timestamp ลง Error Log
• แสดงข้อความที่เข้าใจง่ายใน User Interface
• ใช้ details เพื่อ Highlight ช่องที่กรอกผิด

---

Related Sections

• 09.02 HTTP Status Codes
• 09.04 Authentication Errors
• 09.05 Validation Errors

---

Summary

Standard Error Response Format ช่วยให้ทุก API ของ SISAHYGO มีรูปแบบการตอบกลับเมื่อเกิดข้อผิดพลาดที่เป็นมาตรฐานเดียวกัน ทำให้ Client System สามารถพัฒนา Error Handling ได้ง่ายขึ้น ลดความซับซ้อนของโค้ด และเพิ่มความสามารถในการบำรุงรักษาระบบในระยะยาว

---

Next Step

➡️ 09.04 Authentication Errors