Skip to main content

How to troubleshoot Consumer Report

This guide will help you troubleshoot common issues with Plaid Consumer Report, including tips on using the USER_CHECK_REPORT_READY and USER_CHECK_REPORT_FAILED webhooks, and handling errors like DATA_UNAVAILABLE.

This guide describes the current webhook names. Integrations created before December 10, 2025 receive the legacy CHECK_REPORT_READY / CHECK_REPORT_FAILED webhooks instead — see the Legacy webhook reference section at the bottom of this article.

1. How Consumer Report generation works

After you request a Check Report for a user, the process is asynchronous:

  • When the Check Report is ready: Plaid fires a USER_CHECK_REPORT_READY webhook to your listener.
  • If report generation fails: Plaid fires a USER_CHECK_REPORT_FAILED webhook.

Your backend should be set up to handle these webhooks and respond accordingly.

2. Webhooks

USER_CHECK_REPORT_READY

  • When: Fired when the Check Report is ready to be retrieved (available for 24 hours).
  • What to do: Call one or more of the Consumer Report endpoints, commonly:
  • /cra/check_report/base_report/get
  • /cra/check_report/income_insights/get
  • Action: Retrieve the report for your user.

Example webhook payload:

{
  "webhook_type": "CHECK_REPORT",
  "webhook_code": "USER_CHECK_REPORT_READY",
  "user_id": "usr_wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "successful_products": ["cra_base_report"],
  "environment": "production"
}

USER_CHECK_REPORT_FAILED

  • When: Fired if report generation fails.
  • What to do: 1. Call /user/items/get to diagnose which Items are in a bad state. 2. If needed, use Link's update mode to prompt the user to fix their connection (such as updating credentials or re-authenticating MFA).
  • Action: Initiate troubleshooting — see error codes below.

Example webhook payload:

{
  "webhook_type": "CHECK_REPORT",
  "webhook_code": "USER_CHECK_REPORT_FAILED",
  "user_id": "usr_wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "environment": "production"
}

3. Troubleshooting report errors

When fetching a report, you might encounter certain API errors. These responses often now include a causes field for additional detail on what went wrong.

DATA_UNAVAILABLE

Plaid couldn't retrieve enough data from the user's financial institutions.

Example API error:

{
  "error_type": "CHECK_REPORT_ERROR",
  "error_code": "DATA_UNAVAILABLE",
  "error_message": "The Check Report you are trying to pull does not have sufficient transactions data to generate a report.",
  "causes": [
    {
      "error_type": "ITEM_ERROR",
      "error_code": "ITEM_LOGIN_REQUIRED",
      "error_message": "The login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. Use Link's update mode to restore the Item to a good state.",
      "item_id": "pZ942ZA0npFEa0BgLCV9DAQv3Zq8ErIZhc81F"
    }
  ],
  "request_id": "HNTDNrA8F1shFEW"
}

Common causes (causes field):

  • No transactions returned — the user has no transaction history for the required period, or the account type doesn't support transaction data.
  • No identity data returned — the user's institution does not provide identity data, or the account is not eligible.
  • Issues connecting to financial institution — credentials or MFA settings have changed; the user needs to update their login.

Remediation:

  • Check the causes field for actionable error codes and messages.
  • If the cause is ITEM_LOGIN_REQUIRED, send the user through Link's update mode to fix their connection.
  • If there is insufficient data, let the user know — sometimes a different account may be required.

Other common error codes

CONSUMER_REPORT_EXPIRED

The report was not retrieved within 24 hours. Re-initiate report generation for a fresh report.

PRODUCT_NOT_READY

You tried to fetch before the report finished generating. Wait for the USER_CHECK_REPORT_READY webhook.

INSTITUTION_TRANSACTION_HISTORY_NOT_SUPPORTED

The institution cannot provide the requested history length. Reduce the number of days of data you request.

INSUFFICIENT_TRANSACTION_DATA

Not enough transactions for income or cash-flow insights. Ask the user to link additional accounts, or try again later.

NO_ACCOUNTS

No eligible accounts linked. Confirm accounts are present with the user.

Legacy webhook reference

Integrations created before December 10, 2025 receive the legacy CHECK_REPORT_READY / CHECK_REPORT_FAILED webhooks instead of the USER_* variants documented above. Differences:

  • user_id values are unprefixed (no usr_ prefix).
  • webhook_type is "CHECK_REPORT" in both legacy and current (only webhook_code and user_id format differ).
  • The lifecycle is identical.
  • During migration, integrations may receive both legacy and current events in parallel.

For the full set of legacy-vs-current differences (idempotency, identity object naming, /user/create response shape), see the New User APIs overview.

Related articles