error-shape-taxonomy

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