{"article":{"id":36323745939863,"url":"https://plaid.zendesk.com/api/v2/help_center/en-us/articles/36323745939863.json","html_url":"https://support.plaid.com/hc/en-us/articles/36323745939863-How-to-troubleshoot-Consumer-Reports","author_id":5390778350871,"comments_disabled":true,"draft":false,"promoted":false,"position":0,"vote_sum":0,"vote_count":0,"section_id":36311990432791,"created_at":"2025-11-13T21:48:01Z","updated_at":"2026-06-01T01:59:14Z","name":"How to troubleshoot Consumer Reports","title":"How to troubleshoot Consumer Reports","source_locale":"en-us","locale":"en-us","outdated":false,"outdated_locales":[],"edited_at":"2026-06-01T01:59:14Z","user_segment_id":null,"permission_group_id":1121794,"content_tag_ids":[],"label_names":[],"body":"

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

\n

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.

\n

1. How Consumer Report generation works

\n

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

\n\n

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

\n

2. Webhooks

\n

USER_CHECK_REPORT_READY

\n\n

Example webhook payload:

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

USER_CHECK_REPORT_FAILED

\n\n

Example webhook payload:

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

3. Troubleshooting report errors

\n

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.

\n

DATA_UNAVAILABLE

\n

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

\n

Example API error:

\n
{\n  \"error_type\": \"CHECK_REPORT_ERROR\",\n  \"error_code\": \"DATA_UNAVAILABLE\",\n  \"error_message\": \"The Check Report you are trying to pull does not have sufficient transactions data to generate a report.\",\n  \"causes\": [\n    {\n      \"error_type\": \"ITEM_ERROR\",\n      \"error_code\": \"ITEM_LOGIN_REQUIRED\",\n      \"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.\",\n      \"item_id\": \"pZ942ZA0npFEa0BgLCV9DAQv3Zq8ErIZhc81F\"\n    }\n  ],\n  \"request_id\": \"HNTDNrA8F1shFEW\"\n}\n
\n

Common causes (causes field):

\n\n

Remediation:

\n\n

Other common error codes

\n

CONSUMER_REPORT_EXPIRED

\n

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

\n

PRODUCT_NOT_READY

\n

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

\n

INSTITUTION_TRANSACTION_HISTORY_NOT_SUPPORTED

\n

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

\n

INSUFFICIENT_TRANSACTION_DATA

\n

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

\n

NO_ACCOUNTS

\n

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

\n

Legacy webhook reference

\n

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

\n\n

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

","user_segment_ids":[]}}