Best Practices for Creating Error Code Patterns

Error codes play a crucial role in helping developers, users, and systems understand what went wrong in an application. A well-structured error code pattern improves clarity, debugging, maintainability, and support.

---

🎯 Why Use a Standard Error Code Pattern?

• 🔍 Easier Debugging: Quickly identify the origin and nature of an error.
• 📈 Better Monitoring & Alerts: Group and analyze issues across services.
• 🤝 Improved Developer Experience: Easier to document, troubleshoot, and integrate.
• 📚 Structured Documentation: Helps technical writers and QA teams.

---

🧱 Structure of an Error Code

A best practice for error code formatting follows a modular pattern, for example:

Example: ORD-API-001

Component	Description
ORD	Domain/Service Code (e.g., Order Service)
API	Error Category (e.g., API validation, authentication)
001	Sequential or categorized numeric code for easy identification

---

🔖 Recommended Naming Convention

Part	Format	Example	Description
Domain	3 uppercase letters	ORD, USR, DLV, PRD	Related to the business domain or microservice
Category	2–4 uppercase letters	API, USC, DLV, GRPC, DB	Classifies type of error
Code	3 digits	001 to 999	Incremental or logical grouping

---

🗂️ Suggested Error Categories

Category Code	Category Name	Description
API	API Errors	Errors related to HTTP requests (validation, auth, etc.)
USC	User Service Errors	Specific to user profile, login, registration, etc.
DLV	Delivery/Validation	Errors in delivery services, logistics validation, etc.
GRPC	gRPC Communication	Errors related to gRPC service-to-service communication
DB	Database Errors	Database read/write, connection, schema validation
INT	Integration Errors	External API failures, payment gateway, 3rd-party service issues
SYS	System Errors	Unexpected exceptions, resource limits, timeout

---

🧾 Full Error Code Examples

Error Code	Message	Description
ORD-API-001	Invalid order payload	The request body failed schema validation
ORD-GRPC-002	Failed to fetch pricing from PRD	gRPC call to pricing service failed
USR-USC-003	User email already exists	Business logic validation for duplicate users

---

🧩 Optional Enhancements

1. Localization Support

{
  "error_code": "USR-USC-003",
  "message": "User email already exists",
  "message_i18n": {
    "id": "Email sudah digunakan",
    "fr": "L'e-mail existe déjà"
  }
}

2. Standard Error Response Format

{
  "success": false,
  "error_code": "ORD-API-001",
  "message": "Invalid order payload",
  "details": {
    "field": "quantity",
    "issue": "Must be greater than 0"
  },
  "timestamp": "2025-08-07T17:00:00Z"
}

🧪 Tips for Designing and Maintaining Error Codes

Tip	Description
✅ Prefix with domain/service name	Keep things traceable across microservices
✅ Centralize error definitions	Use a shared config file or database
✅ Avoid magic numbers	Use enums or constants in code
✅ Version your error codes	Allow backward compatibility
✅ Group related codes	Group 100–199 for validation, 200–299 for business logic, etc.
❌ Don’t expose internal exceptions	Convert to user-friendly messages and codes
❌ Don’t reuse error codes	Ensure one code maps to one error type only

📚 Summary
A well-designed error code pattern helps your application scale, improves DX (developer experience), and reduces debugging time. Always keep error codes:

• Predictable
• Descriptive
• Consistent
• Extensible