Troubleshooting for Named Credentials

When callouts from Salesforce use invalid or expired credentials, some external systems return non-standard HTTP status codes, such as 400 or 601, instead of the standard 401 response. To ensure that your callouts work, you can specify other 4xx, 6xx, 7xx, 8xx, and 9xx HTTP status codes that trigger Salesforce to refresh access tokens.

From Setup, in the Quick Find box, enter Named Credentials, and then select Named Credentials. Create or edit an external credential, and in the Additional Status Codes for Token Refresh field, enter the 4xx status codes that your external system returns.

To perform callouts using a named credential, users need access to:

• The principal that’s defined in the external credential. See Enable External Credential Principals.
• The user external credential that holds encrypted tokens to access the target endpoint. Most standard permission sets and profiles have access to the User External Credentials object by default. For the guest user profile, and for some custom permission sets and profiles, you must assign User External Credentials object permissions manually so these users can make authenticated callouts to external systems. See Enable User External Credentials.

Without both of these permissions, callouts can fail.

If you create a named credential for an installed managed package, you must allowlist the package’s namespace before it can make callouts. See Allowed Namespaces for Callouts in Create and Edit a Named Credential.

Named credentials that are created from Apex code in a managed package are disabled for callouts by default. To allow callouts using these named credentials, go to the named credential in Setup, and then turn on Enabled for Callouts. Be aware of security considerations when enabling callouts for named credentials that originate from Apex.