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
Top comments (0)