0
# Error Handling
1

2
Standardized error handling system for Medusa applications, providing consistent error types, codes, and structured error information across the platform.
3

4
## Capabilities
5

6
### MedusaError Class
7

8
A standardized error class that extends the native JavaScript Error with additional metadata including error types, codes, and timestamps.
9

10
```typescript { .api }
11
/**
12
 * Standardized error to be used across Medusa project
13
 * @extends Error
14
 */
15
class MedusaError extends Error {
16
  /**
17
   * Creates a standardized error to be used across Medusa project
18
   * @param type - type of error from MedusaErrorTypes
19
   * @param message - message to go along with error
20
   * @param code - optional error code from MedusaErrorCodes
21
   * @param params - additional parameters passed to Error constructor
22
   */
23
  constructor(type: string, message: string, code?: string, ...params: any);
24
  
25
  /** The type of error, should be one of MedusaErrorTypes */
26
  public type: string;
27
  /** The error message */
28
  public message: string;
29
  /** Optional error code for more specific error identification */
30
  public code?: string;
31
  /** Timestamp when the error was created */
32
  public date: Date;
33
  /** Static reference to error types */
34
  public static Types: typeof MedusaErrorTypes;
35
  /** Static reference to error codes */
36
  public static Codes: typeof MedusaErrorCodes;
37
}
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { MedusaError } from "medusa-core-utils";
44

45
// Basic error with type and message
46
throw new MedusaError(
47
  MedusaError.Types.NOT_FOUND,
48
  "User not found"
49
);
50

51
// Error with type, message, and code
52
throw new MedusaError(
53
  MedusaError.Types.INVALID_DATA,
54
  "Insufficient inventory",
55
  MedusaError.Codes.INSUFFICIENT_INVENTORY
56
);
57

58
// Catching and handling Medusa errors
59
try {
60
  // some operation
61
} catch (error) {
62
  if (error instanceof MedusaError) {
63
    console.log(`Error type: ${error.type}`);
64
    console.log(`Error code: ${error.code}`);
65
    console.log(`Occurred at: ${error.date}`);
66
  }
67
}
68
```
69

70
### Error Types
71

72
Standard error type constants accessible through `MedusaError.Types` for consistent error categorization.
73

74
```typescript { .api }
75
// Access through MedusaError.Types static property
76
MedusaError.Types: {
77
  /** Errors stemming from the database */
78
  DB_ERROR: "database_error";
79
  /** Duplicate entry or resource conflict errors */
80
  DUPLICATE_ERROR: "duplicate_error";
81
  /** Invalid argument passed to a function */
82
  INVALID_ARGUMENT: "invalid_argument";
83
  /** Invalid data format or content */
84
  INVALID_DATA: "invalid_data";
85
  /** Authentication or authorization errors */
86
  UNAUTHORIZED: "unauthorized";
87
  /** Resource not found errors */
88
  NOT_FOUND: "not_found";
89
  /** Operation not allowed in current context */
90
  NOT_ALLOWED: "not_allowed";
91
  /** System in unexpected state */
92
  UNEXPECTED_STATE: "unexpected_state";
93
  /** Resource conflict errors */
94
  CONFLICT: "conflict";
95
  /** Payment authorization failures */
96
  PAYMENT_AUTHORIZATION_ERROR: "payment_authorization_error";
97
};
98
```
99

100
### Error Codes
101

102
Specific error codes accessible through `MedusaError.Codes` for more granular error identification within error types.
103

104
```typescript { .api }
105
// Access through MedusaError.Codes static property
106
MedusaError.Codes: {
107
  /** Insufficient inventory for requested quantity */
108
  INSUFFICIENT_INVENTORY: "insufficient_inventory";
109
  /** Shopping cart is in incompatible state for operation */
110
  CART_INCOMPATIBLE_STATE: "cart_incompatible_state";
111
};
112
```
113

114
**Usage Examples:**
115

116
```typescript
117
import { MedusaError } from "medusa-core-utils";
118

119
// Using error types and codes together
120
if (inventory < requestedQuantity) {
121
  throw new MedusaError(
122
    MedusaError.Types.INVALID_DATA,
123
    "Not enough items in stock",
124
    MedusaError.Codes.INSUFFICIENT_INVENTORY
125
  );
126
}
127

128
// Database operation error
129
try {
130
  await database.save(entity);
131
} catch (dbError) {
132
  throw new MedusaError(
133
    MedusaError.Types.DB_ERROR,
134
    "Failed to save entity to database",
135
    undefined,
136
    dbError
137
  );
138
}
139

140
// Authorization error
141
if (!user.hasPermission("admin")) {
142
  throw new MedusaError(
143
    MedusaError.Types.UNAUTHORIZED,
144
    "Admin access required"
145
  );
146
}