Troubleshooting

If you are having issues with the Admin API, try troubleshooting the issues by stepping through the questions below.

API Configuration

Is the URL Correct?

There are two components to the URL that you may want to check you are using correctly:

  1. Ensure you are using the correct Base URL, and not the Financial Institution environment URL.
  2. Ensure that you are specifying the correct version

Is the authorization header valid?

You may be seeing an error code similar to 401 Unauthorized. It’s likely you are 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 Quickstart for more details on how to obtain an Access Token.

Institution ID in Request Endpoints

Many of the endpoints in the Admin API will require an Institution ID. Unless otherwise specifified, you should use the Institution ID in UUID format.

Associated User Permissions

You may be seeing 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.

403 Error

If you are receiving a 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 to find the specific permissions required.

General Tips

Be careful with copy+pasting

In some of our documentation, you may see instances of <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 more details, we can help. Please use the below template:

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?

Please use this template to create a new Stack Overflow question.

Reminder: Never share private information, such as secret keys.