Best Practices for Handling and Troubleshooting Failed Logins in Salesforce

Any access to a Salesforce organization requires a user login. This includes normal Salesforce application access in a browser, accessing your org via the Salesforce mobile app, and accessing your org programmatically via API calls. Logins can fail for a variety of reasons, including invalid login credentials or org-level issues like incorrect user or org permissions. A single failed login does not incur much overhead; however, many repeated or simultaneous failed logins can result in poor user experience.

In worst-case scenarios, if it’s determined failed logins are affecting general system performance, the IP making the failed login requests could be temporarily blocked to alleviate the issue. Note that this temporary block will also block valid logins coming from the same IP, so you want to fix excessive failed login problems before they get to this point.

Manage Password Expiration Settings

One of the most common causes of unexpected login failures is password expiration. If you attempt to log in with an expired password, you receive an INVALID_OPERATION_WITH_EXPIRED_PASSWORD error ("The user's password has expired, you must call SetPassword before attempting any other API operations").
Write your integration code to gracefully handle this type of login failure. You can also configure your organization to prevent expired passwords for specific user profiles by enabling the "Password Never Expires" setting in the Administrative Permissions section of a profile. A common strategy is to create a dedicated profile for integration users and enable "Password Never Expires" on that profile. Access profile settings via Setup > Manage Users > Profiles.
See About Passwords and Profiles Overview for more information.

Check and Handle Login Errors

There are many causes of unsuccessful logins. Rather than simply retrying the login multiple times until a threshold is met, write your code to check the specific error returned and respond appropriately. Retrying without understanding the error adds unnecessary overhead to your org and creates a poor user experience.

Salesforce provides detailed responses to unsuccessful logins. Depending on which interface you are using to log in to Salesforce, check for the error in the response or catch an exception that contains the error.

Handling SOAP API login errors: When using the SOAP API login() call, catch the LoginFault exception and check its ExceptionCode. If the code is PASSWORD_LOCKOUT, the user has exceeded the number of failed password attempts — log the error and do not retry. If the code is INVALID_LOGIN, the credentials are invalid — prompt the user for the correct credentials and retry. Other exception codes cover scenarios such as API disabled, organization locked, and security token required.
Here’s an abridged example of handling login errors from the SOAP API login() call:

try { 
   // Using binding already set up, log in
   LoginResult = binding.login(username, password);
   // Process successful LoginResult
   ... 
} catch (LoginFault loginFault) { 
   ExceptionCode exCode = loginFault.getExceptionCode();
   if (exCode == ExceptionCode.PASSWORD_LOCKOUT) {
       // User login has exceeded number of failed password attempts
       // Provide details to user or log 
       String errMsg = loginFault.getMessage();
       ...
       // Exit and do not re-attempt to login with this user
       ...
   }
   if (exCode == ExceptionCode.INVALID_LOGIN) {
       // Invalid password or credentials
       // Provide details to user or log
       String errMsg = loginFault.getMessage();
       ...
       // Have user provide correct credentials and re-attempt login
       ...
   }
   // Process other possible errors
   ...
}

See in the SOAP API Developer’s Guide for a full list of possible error codes.

Handling REST API login errors: When using a REST-based API and receiving a 400-level error during login, check the response body for the errorCode and message fields. For example, a failed login returns a JSON response with errorCode: "INVALID_LOGIN" and a message describing the failure.

{
 "message" : "Invalid username, password, security token",
 "errorCode" : "INVALID_LOGIN"
}

 See in the REST API Developer’s Guide for more details on REST API error responses.

Track Login Failures and Re-use Login Sessions Across Integration Jobs

In scenarios where login errors cannot be addressed at the time of failure (for example, multiple integration jobs running on independent systems without user interaction), use an external queue to track the currently in-use login session. Each integration job can check this queue and re-use the already logged-in session. If an unrecoverable login error occurs, a job can mark the session or user ID as invalid so that subsequent integration jobs do not continue attempting logins that will not succeed.

Getting and caching a session ID: Obtain a session ID as part of a successful login response. If you are using a REST-based Salesforce API, you receive a session ID as part of your OAuth authentication process. Cache this session ID and re-use it for subsequent transactions rather than logging in again for each request.

Checking for an expired session: Check the response from transactions to determine if the session has expired. If the session has expired, you receive a "Session expired or invalid" INVALID_SESSION_ID error. When using the SOAP API, catch the UnexpectedErrorFault exception and check whether the ExceptionCode equals INVALID_SESSION_ID. If it does, attempt to refresh the session.

try { 
   // Salesforce transaction using current session
   ... 
} catch (UnexpectedErrorFault uef) { 
   if (uef.ExceptionCode == ExceptionCode.INVALID_SESSION_ID) { 
       // Try and refresh the user session 
       ...
   } 
}

Refreshing the session ID: When a session ID expires and you are using OAuth, request a token refresh by sending a POST request to the OAuth token endpoint with the current refresh token, client ID, and client secret. The response returns a new access token you can use for subsequent transactions. See OAuth 2.0 Refresh Token Flow for details.

Verify API Access Permissions and Monitor API Limits

Even if login credentials are correct, a login can fail for API access due to incorrect API permissions or API limits.

• If you receive an API_DISABLED_FOR_ORG error, the organization does not support API access. API Access is available for Enterprise, Unlimited, Performance, and Developer edition organizations.
• If you receive an API_CURRENTLY_DISABLED error ("API is disabled for this User"), ensure the user profile has the "API Enabled" permission turned on. Access this setting via Setup > Manage Users > Profiles.
• Salesforce limits the number of API calls (including programmatic logins) per 24-hour period based on org edition. If you exceed the limit, you may receive a failed login indicating the request limit has been reached. Limits are documented in the SOAP API Developer's Guide.

Verify the Security Token

Salesforce provides additional validation of user credentials for API logins by requiring a user ID, password, and a security token. Depending on how your Salesforce organization is configured, you may need to include the security token as part of your login.
If you are logging in for API access, append the security token to your password in the login credentials; otherwise you receive a LOGIN_MUST_USE_SECURITY_TOKEN error. If you have configured Trusted IP Ranges and are calling a login from a registered IP address, the security token is not required.
Salesforce generates a security token for each user and notifies the user via email. When a user changes their password, Salesforce also generates a new security token. To reset a security token, go to Settings > My Personal Information > Reset My Security Token. See Resetting Your Security Token for more details.