Troubleshooting

• Common OAuth errors — Connection failing during OAuth
• Common integration issues — API calls returning errors
• JWKS validation issues — Token validation failing
• Logging — Debug a specific flow or unsure where to look
• FDX Explorer — Reference OAuth flow with interactive demo

These are standard OAuth error codes your server should return to Plaid:

If Plaid encounters problems validating your ID tokens, connections will fail and your conversion rates will drop. These issues typically show up as authentication failures in your logs or low conversion metrics in the Data Partner Dashboard. Your Solutions Engineer may reach out to help troubleshoot.

Good logging significantly reduces debugging time. Log the following identifiers for every session:

Plaid sends the X-Request-ID header when calling your token_endpoint and resource server endpoints:

X-Request-ID: req_4h8j2k9m3n7p5q1r

Include these identifiers in support tickets to speed up resolution.

Plaid sends email notifications when integration issues are detected, with a link to the issue in your dashboard. Use the Issue Center to see all active issues at a glance, and drill into individual issue detail pages to debug using error trends, sample errors, and request-level logs.

In addition to responding to alerts, proactively monitor:

• HTTP status codes and latency for authorize, token, userinfo, and jwks_uri endpoints
• Error rates: Alert if > 2%
• OAuth and JWKS errors: Log with timestamp and state

Opening a support ticket? Include:

• state value
• Timestamp and user ID
• Error message and HTTP status
• Request/response headers (mask the secrets!)
• X-Request-ID from the request headers
• Recent log entries surrounding the error

The more context you provide, the faster the resolution.

Beyond standard OAuth errors, watch for these implementation problems:

Issue: API response validation fails because a field contains null instead of the expected data type (string, number, array, etc.).

Cause: Returning null for a field when the schema expects a typed value.

Resolution:

• Required fields: Return a value in the expected type. If data is unavailable, use an empty string ("") for strings or an empty array ([]) for arrays.
• Optional fields: Omit the field entirely from the response rather than setting it to null.

// Don't do this
{
  "email": null,
  "phoneNumbers": null
}

// Do this instead
{
  "email": "",
  "phoneNumbers": []
}

// Or this (omit optional fields)
{
  "email": ""
}

Issue: Plaid limits how many times it will call a paginated endpoint before throwing an error.

Cause: The nextOffset field (or equivalent pagination parameter) is set to null or an empty string on the final page instead of being omitted.

Resolution: On the last page of results, omit the nextOffset field completely. Don't set it to null, empty string, or 0.

Example:

// Don't do this (last page)
{
  "data": [...],
  "nextOffset": null
}

// Do this instead (last page)
{
  "data": [...]
}

Issue: Data Providers trying to debug OAuth issues don't see logs in the Data Partner Dashboard.

Cause: Plaid only provides logs after the user successfully passes initial authentication steps. If the OAuth flow fails during authorization or before the token exchange completes, logs will not be available.

Resolution: Contact Plaid support to review internal logs and identify where the flow broke. Common pre-log issues include: invalid client_id, HTTPS errors, or redirect URI mismatch.

Issue: Refresh token flow fails with invalid_grant error during background updates.

Cause: Refresh token expired before Plaid attempted to use it. This error can occur when the refresh token lifetime is set too short or when the DP revokes tokens after a period of inactivity.

Resolution:

• Set refresh token expiration to 13+ months
• Don't use inactivity timeouts on refresh tokens
• If revocation is necessary, coordinate with Plaid to avoid breaking active connections

Issue: Connection fails because the user identifier (consistency key) returned in the id_token sub field or /customers/current is fewer than seven characters.

Cause: Consistency key too short to meet minimum requirements.

Resolution: Use a longer identifier or a prefix with the institution code, with a minimum length of seven characters.

// Too short
{"sub": "12345"}

// Acceptable length
{"sub": "user_12345"}