Skip to content

09.03 Standard Error Response Format ​


📌 At a Glance ​

รายการรายละเอียด
TopicStandard Error Response Format
Difficulty⭐⭐ Beginner
Reading Time10 นาที
TargetDeveloper, System Integrator
Related APIsAll 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

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


Standard Error Response ​

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

json
{
    "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 ​

text
Error Response

│

├── success

├── message

├── error_code

├── details[]

│      │

│      ├── field

│      └── message

├── timestamp

└── path

Root Fields ​

FieldTypeDescription
successBooleanผลลัพธ์ของคำขอ (false)
messageStringข้อความสรุปของข้อผิดพลาด
error_codeStringรหัสข้อผิดพลาดสำหรับอ้างอิง
detailsArrayรายละเอียดข้อผิดพลาดแต่ละรายการ
timestampDateTimeวันที่และเวลาที่เกิดข้อผิดพลาด
pathStringAPI Endpoint ที่เรียกใช้งาน

Details Object ​

FieldTypeDescription
fieldStringชื่อ Field ที่เกิดข้อผิดพลาด
messageStringรายละเอียดของข้อผิดพลาด

Example : Validation Error ​

http
HTTP/1.1 422 Unprocessable Entity
json
{
    "success": false,
    "message": "Validation failed.",
    "error_code": "ERR-VAL-001",
    "details": [
        {
            "field": "amount",
            "message": "Amount must be greater than zero."
        }
    ]
}

Example : Authentication Error ​

http
HTTP/1.1 401 Unauthorized
json
{
    "success": false,
    "message": "Invalid API Key.",
    "error_code": "ERR-AUTH-001"
}

Example : Resource Not Found ​

http
HTTP/1.1 404 Not Found
json
{
    "success": false,
    "message": "Shipment not found.",
    "error_code": "ERR-NOTFOUND-001"
}

Error Code Convention ​

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

PrefixDescription
ERR-AUTHAuthentication
ERR-VALValidation
ERR-BUSBusiness Rules
ERR-NOTFOUNDResource Not Found
ERR-SERVERInternal Server Error

ตัวอย่าง

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

Client Handling Flow ​

text
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

SISAHYGO API Integration Guide