---

name: error-code-guide description: | Design consistent error codes following the PREFIX_CATEGORY_NUMBER format. Use when: defining error codes, creating error handling, designing APIs. Keywords: error code, error handling, error format, API errors, 錯誤碼, 錯誤處理.

Error Code Guide

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2025-12-30 Applicability: Claude Code Skills

---

Purpose

This skill helps design consistent error codes following the standard format, enabling better debugging, monitoring, and user experience.

Quick Reference

Error Code Format

Copy<PREFIX>_<CATEGORY>_<NUMBER>

Examples

CopyAUTH_VAL_001    → Authentication validation error
PAY_SYS_503     → Payment system unavailable
USR_BIZ_100     → User business rule violation
API_NET_408     → API network timeout

Error Categories

Category Code Ranges

HTTP Status Code Mapping

Detailed Guidelines

For complete standards, see:

• Error Code Standards

AI-Optimized Format (Token-Efficient)

For AI assistants, use the YAML format files for reduced token usage:

• Base standard: ai/standards/error-codes.ai.yaml

Error Response Format

Single Error

Copy{
  "success": false,
  "error": {
    "code": "AUTH_VAL_001",
    "message": "Email is required",
    "field": "email",
    "requestId": "req_abc123"
  }
}

Multiple Errors

Copy{
  "success": false,
  "errors": [
    {
      "code": "AUTH_VAL_001",
      "message": "Email is required",
      "field": "email"
    },
    {
      "code": "AUTH_VAL_201",
      "message": "Password must be at least 8 characters",
      "field": "password"
    }
  ],
  "requestId": "req_abc123"
}

Internal Error Object

Copyinterface ApplicationError {
  // Core fields
  code: string;          // "AUTH_VAL_001"
  message: string;       // Technical message for logs

  // User-facing
  userMessage: string;   // Localized user message
  userMessageKey: string; // i18n key: "error.auth.val.001"

  // Context
  field?: string;        // Affected field: "email"
  details?: object;      // Additional context

  // Debugging
  timestamp: string;     // ISO 8601
  requestId: string;     // Correlation ID
}

Internationalization (i18n)

Message Key Format

Copyerror.<prefix>.<category>.<number>

Example Translation Files

Copy# en.yaml
error:
  auth:
    val:
      001: "Email is required"
      101: "Invalid email format"
    auth:
      001: "Invalid credentials"

# zh-TW.yaml
error:
  auth:
    val:
      001: "電子郵件為必填欄位"
      101: "電子郵件格式無效"
    auth:
      001: "帳號或密碼錯誤"

Examples

✅ Good Error Codes

CopyAUTH_VAL_001  // Missing required field: email
AUTH_VAL_101  // Invalid email format
ORDER_BIZ_001 // Order already cancelled
ORDER_BIZ_201 // Daily purchase limit exceeded
DB_SYS_001    // Database query failed
SEC_AUTH_001  // Invalid credentials
SEC_AUTH_201  // Token expired

❌ Bad Error Codes

CopyERR_001       // Too vague, no prefix or category
INVALID       // Not descriptive
error         // Not a code
AUTH_ERROR    // Missing number

Checklist

• Unique code for each error
• Category matches error type
• User message is localized
• HTTP status is correct
• Error is documented
• Code is in registry

---

Configuration Detection

This skill supports project-specific configuration.

Detection Order

1. Check for existing error code patterns in codebase
2. Check CONTRIBUTING.md for error code guidelines
3. If not found, default to PREFIX_CATEGORY_NUMBER format

First-Time Setup

If no error code standard found:

1. Suggest: "This project hasn't configured error code standards. Would you like to set up an error code registry?"
2. Suggest creating errors/registry.ts:

Copyexport const ErrorCodes = {
  AUTH_VAL_001: {
    code: 'AUTH_VAL_001',
    httpStatus: 400,
    messageKey: 'error.auth.val.001',
    description: 'Email field is required',
  },
  // ... more codes
} as const;

---

Related Standards

• Error Code Standards
• Logging Standards

---

Version History

---

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards