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"
            }
        ]
    }
}

FuseError

Attribute	Descriptions
title string	Title of the error
details string	Details of the error
code string	Error code, see below for possible error codes and how to handle them.
type string	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.
source string	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.
data array of FuseError objects	An array of errors from an aggregator.

Http status codes

Status	Explanation
200 - OK	Everything worked as expected with content returned.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 - Server Errors	Something 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

Code	Explanation
invalid_headers	The request headers provided by the client are invalid
invalid_request_body	Request body is required but missing.
missing_access_token	The request is missing the access token.
request_body_missing	The request body is missing from the client's request.
request_content_type_invalid	Invalid Content-Type header. Must be `application/json`.
request_body_invalid_json	Request body is not a valid JSON format.

Server errors

Code	Explanation
internal_server_error	A generic server-side error that occurred while processing the request.

Header errors

Code	Explanation
missing_plaid_client_id_header	The Plaid client ID header is missing from the request.
missing_plaid_secret_header	The Plaid secret header is missing from the request.
missing_plaid_verification_header	The Plaid verification header is missing from the request.
missing_mx_client_id_header	The MX client ID header is missing from the request.
missing_mx_api_key_header	The MX API key header is missing from the request.
missing_teller_private_key_header	The Teller private key header is missing from the request.
missing_teller_certificate_header	The Teller certificate header is missing from the request.
missing_teller_application_id_header	The Teller application ID header is missing from the request.
missing_teller_signing_secret_header	The Teller signing secret header is missing from the request.
missing_teller_signature_header	The Teller signature header is missing from the request.
missing_fuse_verification_header	The Fuse verification header is missing from the request.

Aggregator Errors

Code	Explanation
aggregator_error	A 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_error	The aggregator has been disconnected from the account and the bank account needs to be reconnected.
aggregator_connection_finished_error	Access 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

Code	Explanation
webhook_error	An 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.