error-shape-taxonomy

name	Error Shape Taxonomy
description	Standard error response taxonomy and envelope for services, including error codes, categories, retryability, correlation IDs, safe messaging, and validation error details

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

Prefix	Category	Example
AUTH_	Authentication	AUTH_001 Token expired
AUTHZ_	Authorization	AUTHZ_001 Permission denied
VAL_	Validation	VAL_001 Invalid email format
BIZ_	Business logic	BIZ_001 Insufficient balance
SYS_	System	SYS_001 Database unavailable
RATE_	Rate limiting	RATE_001 Too many requests

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