Plaid Node.js Client

Common errors

• Plaid API Error: { "error_code": "INVALID_CREDENTIALS", "error_message": "client_id or secret is invalid", ... }

  cause The Plaid API client was initialized with incorrect or missing `PLAID-CLIENT-ID` or `PLAID-SECRET` headers.
  fix Verify that your `PLAID_CLIENT_ID` and `PLAID_SECRET` environment variables (or hardcoded values during development) exactly match your credentials from the Plaid Dashboard for the chosen environment (Sandbox, Development, or Production).

• TypeError: Cannot read properties of undefined (reading 'Configuration') OR PlaidApi is not a constructor

  cause Attempting to use CommonJS `require()` syntax with a library that is primarily designed for ES Modules (ESM) and uses named exports, especially in a modern Node.js project where `type: "module"` is set in `package.json`.
  fix Switch to ES Module `import` statements: `import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';`. If you must use CommonJS, ensure your environment supports it correctly, or investigate if an older version of the library explicitly supported CommonJS exports.

• Plaid API Error: { "error_code": "INVALID_INPUT", "error_message": "'start_date' must be in the format 'YYYY-MM-DD'", ... }

  cause A date field in an API request (e.g., `start_date`, `end_date` for transactions) was not provided in the required `YYYY-MM-DD` string format.
  fix Review the specific endpoint documentation for the correct date format. Ensure all date parameters are formatted as `YYYY-MM-DD` strings. For datetimes, use `YYYY-MM-DDTHH:mm:ssZ`.

Warnings

• breaking Major version bumps of the `plaid-node` client library (e.g., from v8 to v9, or v9 to v42) often introduce breaking changes. Version 9.0.0, released in August 2021, represented a significant interface change due to the transition to an OpenAPI spec-generated client. Always consult the client library changelog and migration guide when upgrading major versions.
  Fix: Review the official Plaid client library changelog on GitHub and the API upgrade guide for specific migration instructions for your target version. Pay close attention to changes in model imports, enum usage, and request/response structures.
• gotcha The `plaid-node` client library is explicitly designed to support the `2020-09-14` Plaid API version. Using an outdated client library or implicitly relying on an older API version can lead to unexpected behavior or missing features.
  Fix: Always ensure your client library is updated to a recent version. Explicitly include `'Plaid-Version': '2020-09-14'` in your request headers via `baseOptions` during `Configuration` initialization to guarantee API version compatibility.
• gotcha When handling errors, logging the full error object directly (e.g., `console.error(error)`) can expose sensitive API keys and secrets embedded in `error.response.config.headers`.
  Fix: Only log specific parts of the error object, such as `error.response.data` for API-specific error details, and avoid logging `error.response.config.headers` or the entire `error` object.
• gotcha Dates and datetimes in Plaid API requests have strict string formatting requirements. `format: date` requires `'YYYY-MM-DD'` and `format: date-time` requires `'YYYY-MM-DDTHH:mm:ssZ'`. Failing to adhere to these formats or omitting time zone information for datetimes will result in an API error.
  Fix: Ensure all date and datetime strings sent in API requests precisely match the specified `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ssZ` (ISO 8601) formats, including the 'Z' for UTC if applicable. For TypeScript, consider using helper functions or libraries to ensure correct formatting.

Install

• npm install plaid npm
• yarn add plaid yarn
• pnpm add plaid pnpm

Imports

• Configuration
  wrong:

  const Configuration = require('plaid').Configuration;

  correct:

  import { Configuration } from 'plaid';

  The library primarily uses named exports and is designed for ESM. CommonJS 'require' syntax will not work as expected with modern versions.
• PlaidApi
  wrong:

  import PlaidApi from 'plaid';

  correct:

  import { PlaidApi } from 'plaid';

  PlaidApi is a named export, not a default export. Ensure you destructure it correctly.
• PlaidEnvironments
  wrong:

  const PlaidEnvironments = require('plaid').PlaidEnvironments;

  correct:

  import { PlaidEnvironments } from 'plaid';

  Used to select the target Plaid environment (e.g., sandbox, production). Like other core components, it's a named export and benefits from TypeScript typing.

Quickstart

This quickstart demonstrates how to initialize the Plaid client with API credentials and environment, then fetch a list of top institutions using the `institutionsGet` endpoint. It includes basic error handling and best practices for environment variables and API versioning.

import { Configuration, PlaidApi, PlaidEnvironments, Products, CountryCode } from 'plaid';

// Replace with your actual Plaid API credentials. Consider using environment variables.
const CLIENT_ID = process.env.PLAID_CLIENT_ID ?? 'your_client_id';
const SECRET = process.env.PLAID_SECRET ?? 'your_secret';

// Configure the Plaid client
const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox, // Or PlaidEnvironments.production for live data
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': CLIENT_ID,
      'PLAID-SECRET': SECRET,
      'Plaid-Version': '2020-09-14', // Recommended to explicitly set the API version
    },
  },
});

const plaidClient = new PlaidApi(configuration);

async function getPlaidInstitutions() {
  try {
    // Define a request to fetch some institutions
    const request = {
      country_codes: [CountryCode.Us],
      products: [Products.Auth],
      count: 5,
      offset: 0,
    };
    const response = await plaidClient.institutionsGet(request);
    console.log('Successfully fetched top 5 Institutions:');
    response.data.institutions.forEach(inst => console.log(`- ${inst.name} (ID: ${inst.institution_id})`));
    return response.data.institutions;
  } catch (error: any) {
    if (error.response) {
      // Log only necessary parts to avoid exposing secrets in error.response.config.headers
      console.error('Plaid API Error:', error.response.data);
    } else {
      console.error('Plaid Client Error:', error.message);
    }
    throw error;
  }
}

// Run the example
PlaidEnvironments.sandbox === configuration.basePath ?
  getPlaidInstitutions().then(() => console.log('\nExample complete using Sandbox environment.')) :
  console.warn('Warning: Not running institution fetch in non-sandbox environment for quickstart.');