User Not Found Error

https://bessapay.net/errors/user-not-found

Overview

A User Not Found error occurs when an operation attempts to access or modify a user that does not exist in the system. This error is returned with HTTP status code 404.

Details

Error Code: USER_NOT_FOUND
HTTP Status: 404
Error Type: Client Error

Common scenarios

• Looking up a user by an invalid ID
• User has been deleted
• Attempting to modify a non-existent user
• Incorrect email address during login
• Typo in username or user identifier

Example

User Not Found Error Response

1{
2  "type": "https://bessapay.net/errors/user-not-found",
3  "title": "User Not Found",
4  "status": 404,
5  "detail": "The user with ID 'usr_12345' could not be found",
6  "instance": "/api/v1/users/usr_12345",
7  "errorCode": "USER_NOT_FOUND",
8  "timestamp": "2023-06-15T20:05:30Z"
9}

How to Handle

Verify user identifiers

Double-check that you're using the correct user ID, email, or username. Watch for typos and ensure that you're using the exact identifier.

Check if the user was deleted

If the user previously existed, they may have been deleted. Consider implementing a way to retrieve archived or soft-deleted users if needed.

Implement user creation flow

During sign-in attempts, redirect to a sign-up page if the user doesn't exist. This provides a smoother experience for new users.

Sign-in with Fallback to Sign-up

1// Example of handling User Not Found during authentication
2async function handleSignIn(email, password) {
3  try {
4    const response = await fetch('https://api.semuni.com/v1/auth/signin', {
5      method: 'POST',
6      headers: {
7        'Content-Type': 'application/json'
8      },
9      body: JSON.stringify({ email, password })
10    });
11    
12    if (response.status === 404) {
13      const errorData = await response.json();
14      
15      // Check if specifically a user not found error
16      if (errorData.type === 'https://bessapay.net/errors/user-not-found') {
17        // Show message and offer sign-up option
18        return {
19          success: false,
20          errorType: 'userNotFound',
21          message: 'No account found with this email address',
22          actions: [
23            { type: 'signup', label: 'Create an account', email },
24            { type: 'tryAnother', label: 'Try another email' }
25          ]
26        };
27      }
28    }
29    
30    if (!response.ok) {
31      const errorData = await response.json();
32      throw new Error(errorData.detail || 'Sign-in failed');
33    }
34    
35    // Success case
36    const authData = await response.json();
37    return {
38      success: true,
39      authData
40    };
41  } catch (error) {
42    console.error('Sign-in error:', error);
43    return {
44      success: false,
45      errorType: 'error',
46      message: 'An error occurred during sign-in. Please try again.'
47    };
48  }
49}

Implement user search

If users are looking up other users (e.g., for sending payments), implement a search function that helps find users by partial matches on names or usernames, rather than requiring exact IDs.

Code Example: User Lookup with Graceful Handling

User Lookup with Suggestions

1// Example of handling User Not Found with suggestions
2async function lookupUser(userIdentifier) {
3  try {
4    // Try direct lookup first
5    const response = await fetch(`https://api.semuni.com/v1/users/${encodeURIComponent(userIdentifier)}`, {
6      headers: {
7        'Authorization': `Bearer ${apiKey}`,
8        'Content-Type': 'application/json'
9      }
10    });
11    
12    if (response.status === 404) {
13      // User not found, try searching for similar users
14      const searchResponse = await fetch(
15        `https://api.semuni.com/v1/users/search?query=${encodeURIComponent(userIdentifier)}`,
16        {
17          headers: {
18            'Authorization': `Bearer ${apiKey}`,
19            'Content-Type': 'application/json'
20          }
21        }
22      );
23      
24      if (searchResponse.ok) {
25        const searchResults = await searchResponse.json();
26        
27        if (searchResults.users && searchResults.users.length > 0) {
28          // Found similar users
29          return {
30            success: false,
31            errorType: 'userNotFound',
32            message: `User "${userIdentifier}" not found, but we found similar users:`,
33            suggestions: searchResults.users.slice(0, 5),
34            actions: [
35              { type: 'select', label: 'Select from results' },
36              { type: 'search', label: 'Try another search' }
37            ]
38          };
39        }
40        
41        // No similar users found
42        return {
43          success: false,
44          errorType: 'userNotFound',
45          message: `No users found matching "${userIdentifier}"`,
46          actions: [
47            { type: 'search', label: 'Try another search' },
48            { type: 'invite', label: 'Invite user' }
49          ]
50        };
51      }
52      
53      // Search also failed
54      return {
55        success: false,
56        errorType: 'userNotFound',
57        message: `User "${userIdentifier}" not found`,
58        actions: [
59          { type: 'search', label: 'Try another search' }
60        ]
61      };
62    }
63    
64    if (!response.ok) {
65      const errorData = await response.json();
66      throw new Error(errorData.detail || 'User lookup failed');
67    }
68    
69    // Success case
70    const userData = await response.json();
71    return {
72      success: true,
73      user: userData
74    };
75  } catch (error) {
76    console.error('User lookup error:', error);
77    return {
78      success: false,
79      errorType: 'error',
80      message: 'An error occurred during user lookup. Please try again.'
81    };
82  }
83}