Error Shape Taxonomy

Overview

มาตรฐาน error response format ที่ใช้ทั้งองค์กร ครอบคลุม error codes, categories, และ structure ที่ทำให้ client และ monitoring tools เข้าใจ error ได้ทันที

Why This Matters

• •Debuggability: รู้ทันทีว่า error มาจากไหน ทำไม
• •Client handling: Frontend/mobile handle errors ได้ถูกต้อง
• •Monitoring: Alert และ dashboard แยก error types ได้
• •Documentation: Error catalog ที่ reference ได้

Core Concepts

1. Error Envelope Structure

• •แนะนำให้ยึดแนวคิด RFC 7807 (problem details) แต่ให้คงโครงเดียวกันทั้งองค์กร
• •ต้องมี: code, message, requestId, timestamp, status
• •ถ้าเป็น retryable ให้มี retryable และ retryAfterSeconds (ถ้ามี)

2. Error Code System

• •PREFIX_### หรือ PREFIX_SUB_### (อ่านง่าย, stable)
• •code ต้อง คงที่ (ห้ามเปลี่ยนความหมาย) และต้อง document ใน catalog
• •หลีกเลี่ยงใช้ HTTP status เป็น code (เช่น ERR_500) เพราะไม่สื่อสาเหตุ

3. Error Categories

กำหนดหมวดให้ชัดเพื่อ routing/alert:

• •AUTH_ / AUTHZ_: authn/authz
• •VAL_: validation / malformed requests
• •BIZ_: business/domain rules
• •RATE_: rate limiting / quotas
• •SYS_: infra/system dependencies (DB, queue, upstream)

4. Error Messages

• •message ต้องเป็น user-safe (ไม่เปิดเผย stacktrace/SQL/secret)
• •รายละเอียดเชิงเทคนิคให้ใส่ใน details (และต้อง scrub PII/secret)
• •ถ้าต้องการข้อความที่ UI แสดง ให้มี userMessage แยก (optional) และรองรับ i18n

5. Error Context

• •ทุก error ต้องมี requestId (correlation) และควรมี traceId ถ้ามี tracing
• •path และ method ช่วย debug ได้เร็ว (optional)
• •stacktrace ห้ามส่งกลับ client; ให้เก็บใน logs เท่านั้น

6. Localization

• •ถ้ารองรับหลายภาษา: client ใช้ Accept-Language และ server map เป็น userMessage
• •ไม่ควร encode ภาษาไว้ใน code (code ควรเป็นภาษากลาง)

7. Error Mapping

• •map internal errors → external errors แบบ deterministic และทดสอบได้
• •errors จาก upstream ต้อง normalize เข้าสู่ shape มาตรฐานของเรา
• •status ต้องสะท้อน semantics (เช่น VAL_ ส่วนใหญ่เป็น 400/422)

8. Error Documentation

• •มี “error catalog” ต่อ service หรือองค์กร: code, status, meaning, client action, retryable
• •ใช้เป็นแหล่งข้อมูลสำหรับ client SDK, docs, และ alert routing

Quick Start

export type ErrorCategory = "AUTH" | "AUTHZ" | "VAL" | "BIZ" | "RATE" | "SYS";

export interface ErrorResponse {
  error: {
    code: string;
    category: ErrorCategory;
    message: string;
    status: number;
    requestId: string;
    timestamp: string;
    path?: string;
    method?: string;
    retryable?: boolean;
    retryAfterSeconds?: number;
    details?: Record<string, unknown>;
    validationErrors?: Array<{ field: string; reason: string }>;
  };
}

Production Checklist

• • All errors follow standard shape
• • Error codes documented in catalog
• • User-safe messages (no sensitive data)
• • Request ID included in all errors
• • Error logging consistent

Standard Error Shape

// Example payload (VAL_)
// {
//   "error": {
//     "code": "VAL_001",
//     "category": "VAL",
//     "message": "Invalid request",
//     "status": 422,
//     "requestId": "req-789",
//     "timestamp": "2024-01-15T10:00:00Z",
//     "validationErrors": [
//       { "field": "email", "reason": "Invalid email format" }
//     ]
//   }
// }

Error Code Taxonomy

Status + Retryability Guidelines

• •401/403: ไม่ควร retry แบบอัตโนมัติ (ต้องแก้ credential/permission)
• •400/422: ไม่ควร retry (ต้องแก้ request)
• •409: retry ได้ในบางกรณี (ใช้ backoff) ถ้าเป็น conflict ชั่วคราว
• •429: retry ได้ โดยใช้ Retry-After
• •503/504: retry ได้ (bounded retries + jitter)

Anti-patterns

1. •Generic errors: "Something went wrong"
2. •Leaking internals: Stack traces to client
3. •Inconsistent shape: Different format per service
4. •Missing correlation: No request ID
5. •Changing meaning: เปลี่ยน semantics ของ code เดิม ทำให้ client/alert พัง

Integration Points

• •API gateways (error transformation)
• •Frontend error boundaries
• •Monitoring/alerting
• •Documentation generators

Further Reading

• •RFC 7807 Problem Details
• •API Error Handling Best Practices