Skip to main content
A customer may encounter errors inside the Meld Connect Widget while trying to make a connection. Examples include requesting a product you do not have enabled with the service provider, hitting test connection limits, or transient service provider failures. This page is for developers debugging failed connections — it explains how to query widget errors and what each error subtype means.

​
Before you begin

  • You have a Meld API key for the environment in question (sandbox or production)
  • You know either the connectionId of the failed attempt, or a date range you want to inspect
  • You are comfortable querying the Meld Activity Log

​
How to query widget errors

Widget errors are recorded in the Activity Log. Query them by filtering on the action INSTITUTION_CONNECTION_WIDGET_ERROR: 
curl --location 'https://api-sb.meld.io/activity-log?start=2024-05-08T00:00:00.000Z&end=2024-05-10T00:00:00.000Z&connectionId=W9343jnjn3jn3&actions=INSTITUTION_CONNECTION_WIDGET_ERROR' \
--header 'Meld-Version: 2022-11-10' \
--header 'Content-Type: application/json' \
--header 'Authorization: BASIC ***Redacted API Key***'
For the full Activity Log schema and supported query parameters, refer to the API reference.

​
Widget error subtypes

There are three event types (subtypes) of widget errors. Filter by one or more using the eventTypes query parameter on the Activity Log endpoint.
Event typeWhat it meansRecommended developer action
SERVICE_PROVIDER_INITIALIZATION_FAILUREThe widget could not initialize with the underlying service provider. Common causes: the requested product is not enabled on your provider account, missing provider credentials, or invalid configuration in the dashboard.Check that the products you requested in /connect/start are enabled with the provider for your account. Verify provider credentials in the Meld dashboard. If the issue persists, contact Meld support with the connection id.
SERVICE_PROVIDER_FAILUREThe service provider returned an error during the customer’s session. Common causes: institution outage, provider rate limit, expired provider session, or customer-side issues such as repeated invalid credentials.Inspect the serviceProviderDetails in the activity log entry. If the institution is unhealthy, advise the customer to retry later or use a different provider via routing. If you see repeated provider rate-limit errors, throttle test traffic.
INTERNAL_FAILUREAn unexpected error inside Meld occurred during the widget flow.Retry the connection. If the error persists, contact Meld support with the connectionId and the timestamp.

​
Common scenarios and fixes

SymptomLikely causeDeveloper action
Widget fails immediately on launchThe connect token expired (older than 3 hours) or was malformedGenerate a fresh token via /connect/start and relaunch
Picker is empty or has very few institutionsToo many required products or an overly restrictive region filterReduce the products array, move non-essential products to optionalProducts, or remove regions
”Error creating user” when selecting an institutionYou re-enabled a service provider with the same customerId / externalCustomerId used before disablingUse new customerId / externalCustomerId values when reconnecting via a re-enabled provider
Customer sees “Institution unavailable” or a routing retry screenProvider’s integration with that institution is degradedEncourage the customer to use Routing Retry to try another provider; consider enabling Smart Routing in the dashboard
Connection completes but no webhooks fireWebhook profile not configured or filtered too narrowlyVerify your webhook profile per Webhook Quickstart and confirm event types include bank linking events
Sandbox vs. productionWidget errors are logged identically in sandbox (api-sb.meld.io) and production (api.meld.io). Sandbox traffic may produce additional SERVICE_PROVIDER_FAILURE entries that mirror the test behavior of each provider’s sandbox; these are expected and do not indicate a real outage.