0
# Error Handling
1

2
Passport OAuth2 provides specialized error classes for different OAuth 2.0 failure scenarios, each with proper error codes and HTTP status mapping following RFC 6749 specifications.
3

4
## Capabilities
5

6
### AuthorizationError
7

8
Represents errors in response to authorization requests, following RFC 6749 section 4.1.2.1.
9

10
```javascript { .api }
11
/**
12
 * Authorization error constructor
13
 * @param message - Human-readable error description
14
 * @param code - OAuth 2.0 error code
15
 * @param uri - URI reference for additional error information
16
 * @param status - HTTP status code
17
 */
18
function AuthorizationError(message, code, uri, status);
19
```
20

21
**Properties:**
22
- `name`: "AuthorizationError"
23
- `message`: Error description
24
- `code`: OAuth error code (default: 'server_error')
25
- `uri`: Error URI reference
26
- `status`: HTTP status code with automatic mapping:
27
  - `access_denied` → 403
28
  - `server_error` → 502
29
  - `temporarily_unavailable` → 503
30
  - Default → 500
31

32
**Usage Example:**
33

34
```javascript
35
const { AuthorizationError } = require('passport-oauth2');
36

37
// Create authorization error
38
const error = new AuthorizationError(
39
  'The user denied the request',
40
  'access_denied',
41
  'https://example.com/error',
42
  403
43
);
44

45
console.log(error.name);    // "AuthorizationError"
46
console.log(error.code);    // "access_denied"
47
console.log(error.status);  // 403
48
```
49

50
### TokenError
51

52
Represents errors received from token endpoints, following RFC 6749 section 5.2.
53

54
```javascript { .api }
55
/**
56
 * Token error constructor
57
 * @param message - Human-readable error description
58
 * @param code - OAuth 2.0 error code (default: 'invalid_request')
59
 * @param uri - URI reference for additional error information
60
 * @param status - HTTP status code (default: 500)
61
 */
62
function TokenError(message, code, uri, status);
63
```
64

65
**Properties:**
66
- `name`: "TokenError"
67
- `message`: Error description
68
- `code`: OAuth error code (default: 'invalid_request')
69
- `uri`: Error URI reference
70
- `status`: HTTP status code (default: 500)
71

72
**Common OAuth Token Error Codes:**
73
- `invalid_request`: The request is missing a required parameter
74
- `invalid_client`: Client authentication failed
75
- `invalid_grant`: The authorization grant is invalid
76
- `unauthorized_client`: Client is not authorized for this grant type
77
- `unsupported_grant_type`: Grant type is not supported
78
- `invalid_scope`: Requested scope is invalid
79

80
**Usage Example:**
81

82
```javascript
83
const { TokenError } = require('passport-oauth2');
84

85
// Create token error
86
const error = new TokenError(
87
  'The authorization code is invalid',
88
  'invalid_grant',
89
  'https://example.com/error/invalid_grant',
90
  400
91
);
92

93
console.log(error.name);    // "TokenError"
94
console.log(error.code);    // "invalid_grant"
95
console.log(error.status);  // 400
96
```
97

98
### InternalOAuthError
99

100
Wraps errors generated by the node-oauth library, providing better error formatting and debugging information.
101

102
```javascript { .api }
103
/**
104
 * Internal OAuth error constructor
105
 * @param message - Human-readable error description
106
 * @param err - Original error object from node-oauth
107
 */
108
function InternalOAuthError(message, err);
109

110
/**
111
 * Returns formatted string representation of the error
112
 * @returns String representation including OAuth error details
113
 */
114
InternalOAuthError.prototype.toString = function();
115
```
116

117
**Properties:**
118
- `name`: "InternalOAuthError"
119
- `message`: Error description
120
- `oauthError`: Original error object from node-oauth
121

122
**Error Formatting:**
123
The `toString()` method provides enhanced error information:
124
- If `oauthError` is an Error object, returns the original error string
125
- If `oauthError` has `statusCode` and `data`, includes both in format: `(status: 400 data: {"error":"invalid_request"})`
126
- Otherwise returns the standard error message
127

128
**Usage Example:**
129

130
```javascript
131
const { InternalOAuthError } = require('passport-oauth2');
132

133
// Wrap an OAuth error
134
const originalError = {
135
  statusCode: 400,
136
  data: '{"error":"invalid_request","error_description":"Missing client_id"}'
137
};
138

139
const error = new InternalOAuthError('Failed to obtain access token', originalError);
140

141
console.log(error.name);        // "InternalOAuthError"
142
console.log(error.message);     // "Failed to obtain access token"
143
console.log(error.oauthError);  // Original error object
144
console.log(error.toString());  // Enhanced error string with status and data
145
```
146

147
## Error Handling in Strategy
148

149
The OAuth2Strategy automatically creates appropriate error objects during the authentication flow:
150

151
```javascript
152
// In OAuth2Strategy implementation
153
try {
154
  // OAuth operations
155
} catch (err) {
156
  if (err.statusCode && err.data) {
157
    // Try to parse as OAuth error response
158
    const parsedError = this.parseErrorResponse(err.data, err.statusCode);
159
    if (parsedError) {
160
      return this.error(parsedError); // TokenError or custom error
161
    }
162
  }
163
  // Fallback to InternalOAuthError
164
  return this.error(new InternalOAuthError('OAuth request failed', err));
165
}
166
```
167

168
## Error Response Parsing
169

170
The strategy includes a virtual `parseErrorResponse` method that can be overridden for provider-specific error handling:
171

172
```javascript { .api }
173
/**
174
 * Parse error response from OAuth 2.0 endpoint (virtual method)
175
 * Override this method to handle provider-specific error formats
176
 * @param body - Response body string
177
 * @param status - HTTP status code
178
 * @returns TokenError instance or null if parsing fails
179
 */
180
OAuth2Strategy.prototype.parseErrorResponse = function(body, status);
181
```
182

183
**Default Implementation:**
184

185
```javascript
186
OAuth2Strategy.prototype.parseErrorResponse = function(body, status) {
187
  try {
188
    const json = JSON.parse(body);
189
    if (json.error) {
190
      return new TokenError(json.error_description, json.error, json.error_uri);
191
    }
192
  } catch (e) {
193
    // Parsing failed, return null
194
  }
195
  return null;
196
};
197
```
198

199
**Custom Error Parsing Example:**
200

201
```javascript
202
class CustomOAuth2Strategy extends OAuth2Strategy {
203
  parseErrorResponse(body, status) {
204
    try {
205
      const json = JSON.parse(body);
206
      // Handle provider-specific error format
207
      if (json.errorCode) {
208
        return new TokenError(json.errorMessage, json.errorCode, json.helpUrl, status);
209
      }
210
    } catch (e) {
211
      // Fallback to parent implementation
212
      return super.parseErrorResponse(body, status);
213
    }
214
    return null;
215
  }
216
}
217
```