Handling and Troubleshooting API Error Responses

The Fuse API adheres to standard HTTP response codes to indicate the outcome of a request. In the event of a failure, additional error messaging will be provided within the response body to assist in troubleshooting. The error will be in the following format:

    "request_id": "742c3a9d-f411-4ef1-b8c8-312933e0acd2",
    "title": "Aggregator Error",
    "details": "An error occurred while communicating with an aggregator, see data for details",
    "code": "aggregator_error",
    "type": "server_error",
    "source": "aggregator",
    "data": {
        "aggregator": "mx",
        "errors": [
                "request_id": null,
                "title": "MX Error",
                "details": "Couldn't find User record(s) with the information provided.",
                "code": "not_found",
                "type": "record_not_found_error",
                "source": "aggregator"


Title of the error
Details of the error
Error code, see below for possible error codes and how to handle them.
Possible values are AUTH_ERROR, NOT_FOUND, BAD_REQUEST, and SERVER_ERROR. These error types provide a high-level categorization of the errors that can occur while interacting with the Fuse API. AUTH_ERROR indicates an authentication-related issue, such as missing or invalid credentials. NOT_FOUND means the requested resource could not be found. BAD_REQUEST signifies that the client's request was malformed or contained invalid data. SERVER_ERROR represents a general server-side error that occurred while processing the client's request.
Possible values are internal and aggregator. Indicates the source of the error. internal means the error is from Fuse internal server, aggregator means the error is from an external financial connection aggregator like plaid, mx, teller etc.
array of FuseError objects
An array of errors from an aggregator.

Http status codes

200 - OKEverything worked as expected with content returned.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedNo valid API key provided.
402 - Request FailedThe parameters were valid but the request failed.
403 - ForbiddenThe API key doesn't have permissions to perform the request.
404 - Not FoundThe requested resource doesn't exist.
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 - Server ErrorsSomething went wrong with Fuse or upstream aggregator servers

The Fuse API uses the following error codes

Below outlines the different error codes that can be returned by the Fuse API. These error codes help clients understand the nature of the issues that might arise while using the API.

Client errors

invalid_headersThe request headers provided by the client are invalid
invalid_request_bodyRequest body is required but missing.
missing_access_tokenThe request is missing the access token.
request_body_missingThe request body is missing from the client's request.
request_content_type_invalidInvalid Content-Type header. Must be application/json.
request_body_invalid_jsonRequest body is not a valid JSON format.

Server errors

internal_server_errorA generic server-side error that occurred while processing the request.

Header errors

missing_plaid_client_id_headerThe Plaid client ID header is missing from the request.
missing_plaid_secret_headerThe Plaid secret header is missing from the request.
missing_plaid_verification_headerThe Plaid verification header is missing from the request.
missing_mx_client_id_headerThe MX client ID header is missing from the request.
missing_mx_api_key_headerThe MX API key header is missing from the request.
missing_teller_private_key_headerThe Teller private key header is missing from the request.
missing_teller_certificate_headerThe Teller certificate header is missing from the request.
missing_teller_application_id_headerThe Teller application ID header is missing from the request.
missing_teller_signing_secret_headerThe Teller signing secret header is missing from the request.
missing_teller_signature_headerThe Teller signature header is missing from the request.
missing_fuse_verification_headerThe Fuse verification header is missing from the request.

Aggregator Errors

aggregator_errorA generic aggregator error occurred. This error type will contain embedded error codes from the specific aggregator (such as Plaid, Teller, or MX) if they are unable to perform an action like retrieving balances. In such cases, the client should handle it or display a generic error message to the user.
Plaid has well documented errors on this.
aggregator_disconnected_errorThe aggregator has been disconnected from the account and the bank account needs to be reconnected.
aggregator_connection_finished_errorAccess to the financial institution has been revoked and cannot be reestablished automatically. In the event that the user returns to your application, a new financial connection must be initiated and established for the user to regain access to their financial data.

Webhook Errors

webhook_errorAn error occurred while processing a webhook event.

Handling Errors

Clients should handle these error codes and display appropriate error messages to their users. If clients encounter any aggregator errors that they find interesting or believe Fuse can resolve, they should report the issues to Fuse.

Fuse tracks these errors internally to determine the most reliable aggregator for each bank connection. This information is used to update the decision engine, which selects the best aggregator for each customer's user based on their bank connection.