Troubleshooting
General Tips
Be careful with copying and pasting
In some of our documentation, you may see instances of text like <api_key> or {ACCESS_TOKEN}.
In general, these are meant as “fill in the blank” type examples, where you will need to fill in your own inputs. The brackets (<>, {}, or []) should not be included in your final input.
5xx error codes
In general, if you are receiving an error code in the 5xx range, there is an issue with the server itself.
It’s hard to generally say what the issue is, but usually, it’s best to simply try again later.
Common reasons for a 5xx is maintenance or an intermittent error.
Other troubleshooting
If you’re still having issues, we encourage you to read our documentation for more clarity.
We also have a regularly scheduled technical office hours session where we are able to answer live Q&A from the audience. You can register here.
We also recommend checking out the official tag on Stack Overflow.
Error support
From time to time, users receive errors that they are unable to troubleshoot on their own. With some details, we can help. Please use the template below to create a new Stack Overflow question.
x-request-id: This can be found in your error response
Date: Date and time of request
Client ID: What client ID are you using for your request?
Authentication URL: What URL are you using to authenticate?
Redirect URL: What redirect URL are you specifying?
Plugin Error Support
If you are specifically having issues with your plugin, please provide detailed steps to reproduce your problem. It is especially useful if you can provide a usable sample plugin, using either the simple-plugin-example or basic-plugin-example.
Network connectivity
These are general suggestions to diagnose and troubleshoot network connectivity errors on your device.
- Use a fully public URL on a standard port when serving up content from your web server.
- Ensure all resources are served using https (without mixing and matching http content).
- Use a public network and not an internal Wi-Fi connection nor VPN.
- If using a mobile device, turn off Wi-Fi on the device and use the cellular service (or the reverse).
Signing into JackHenry.Dev
These steps may be helpful to troubleshoot when signing into the JackHenry.Dev developer portal.
Signing up for the first time
If you (or your company) are using Google Workspace (formerly G Suite), then it’s possible that your Google Workspace administrator has denied access to third party apps (e.g., the one we use to offer Sign in with Google to create a developer account).
Please have your Google Workspace administrator review these steps to grant access: https://support.google.com/a/answer/7281227?hl=en
Logging in again after previously signing up
If you have previously signed up and are having trouble logging in again, then you may need to try these steps.
Refresh the browser page
Many issues are resolved by refreshing the browser page and signing in again.
If that does not work, then you may need to force a hard refresh of cached data. The steps to do so depend on the combination of your browser and operating system. These are the keyboard shortcuts for common browsers and operating systems.
Chrome, Firefox, or Edge for Windows: Ctrl+F5 (or Shift+F5 or Ctrl+Shift+R)
Chrome or Firefox for Mac: Shift+Command+R
Safari for Mac: Command+Option+R
Delete cookies
If refreshing the browser page does not work, then you may need to clear the cookies for jackhenry.dev and try signing in again.
JackHenry.Dev configuration options
Updating the primary redirect URI
If you are using the JackHenry.Dev developer portal, make sure that the primary redirect URI is correctly set.
It is important to note that more than one redirect URI can be configured, however only one is designated as the primary redirect URI. Double check your configuration to make sure that the URI you expect is correctly set as the primary redirect URI.
Configuring a plugin
If you are using the JackHenry.Dev developer portal, you are able to configure some aspects of your development plugin.
It is important to press the Save button after making any changes to have your plugin update correctly.
Consumer API
If you are having issues with the Consumer API, try troubleshooting the issues by stepping through the questions below.
Is the URL correct?
There are two components to the URL that you may want to check you are using correctly:
- Ensure you are using the correct Base URL for the Consumer API.
- Ensure that you are specifying the correct Version for the Consumer API.
Is the authorization header valid?
If you see an error code similar to 401 Unauthorized, then you are most likely not properly sending your authorization.
Clients must send their Access Token through the Authorization header when making a request.
A basic cURL example looks something like this:
https://example.com
-H "Accept: application/json"
-H "Authorization: Bearer {ACCESS TOKEN}"
See the Authentication (Command Line) quickstart for more details on how to obtain an Access Token for the Consumer API.
Is the request returning an error related to data access?
If you see an error code similar to 403 Forbidden, this means that you are properly authenticated, but the Access Token does not have the required level of access for the resource you are requesting.
If the request is returning an error related to scopes and claims, your application may not be properly configured to request the data you are trying to access.
- Scopes can be configured in your request header when authenticating.
- Claims enable extra data properties in the
id_tokenand responses from the user info endpoint, and must be configured via your external application.
More information about scopes and claims is available in our Authentication Framework docs.
Admin API
If you are having issues with the Admin API, try troubleshooting the issues by stepping through the questions below.
Is the URL correct?
There are two components to the URL that you may want to check you are using correctly:
- Ensure you are using the correct Base URL for the Admin API.
- Ensure that you are specifying the correct Version for the Admin API.
Many of the endpoints in the Admin API will require an Institution ID. Unless otherwise specified, you should use the Institution ID in UUID format.
Is the authorization header valid?
If you see an error code similar to 401 Unauthorized, then you are most likely not properly sending your authorization.
Clients must send their Access Token through the Authorization header when making a request.
A basic cURL example looks something like this:
https://example.com
-H "Accept: application/json"
-H "Authorization: Bearer {ACCESS TOKEN}"
See our Authentication - Client Credentials (Command Line) quickstart for more details on how to obtain an Access Token for the Admin API.
Is the request returning an error related to data access?
If you see an error code similar to 403 Forbidden, this means that you are properly authenticated, but the Access Token does not have the required level of access for the resource you are requesting.
If you are receiving an HTTP 403 error, it’s possible that the Associated User does not have the appropriate permissions granted for that specific endpoint. See the API Reference for the specific endpoint to find the specific permissions required.
Plugin Framework
Are you testing all supported browsers and operating systems?
When testing your plugin, verify that your browser testing covers all browsers and operating systems supported by Banno.
Related to browsers you may need to enable special settings specific to development in order to test.
- For Chromium-based browsers, you’ll have to configure the browser to allow 3rd party cookies.
- For Firefox, you’ll have to enable 3rd party cookies.
- For Safari, you’ll have to disable the “Prevent cross-site tracking” option. You may also need to enable the option Disable local file rescrictions and/or Disable cross-origin rescrictions from the Developer settings.
Using Windows Server
If your plugin hosted on a Windows Server is failing to load on Android devices, the problem might be stemming from an Untrusted Certificate Error. This often occurs if the Windows server doesn’t present a full certificate chain. Android devices, lacking the full chain, cannot verify the server and so prevent the plugin from loading.
To resolve this issue, you need to ensure that the full certificate chain is correctly installed on your server. More information on this, can be found on Sectigo.
Verify your certificate configuration to ensure proper communication between the server and Android devices.
Plugin Framework Bridge
Resource Loading Priority
To ensure that the Plugin Framework Bridge functions correctly, make sure that there are no conflicting scripts loaded first. Sometimes there can be timing issues with the Plugin Bridge, so try to make sure it has the highest loading priority.