Postconditions: what we check

• linkTokenCreate · api-error

  error
  WhenPlaid API error (INVALID_REQUEST, INVALID_INPUT, RATE_LIMIT_EXCEEDED, API_ERROR) or network failure connecting to Plaid.
  ThrowsAxios error. Access PlaidError via error.response.data. Fields include: error_type (e.g. 'RATE_LIMIT_EXCEEDED', 'API_ERROR'), error_code, error_message, request_id.
  Required handlingCaller MUST wrap in try-catch. A failed linkTokenCreate means the user cannot open Plaid Link at all. Handle RATE_LIMIT_EXCEEDED with backoff; return a 5xx to the client for API_ERROR. Never surface raw Plaid errors to end users.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• itemPublicTokenExchange · api-error

  error
  WhenINVALID_INPUT / INVALID_PUBLIC_TOKEN (token already exchanged, expired, or malformed) or API_ERROR (internal Plaid error) or network failure.
  ThrowsAxios error with PlaidError in error.response.data. INVALID_PUBLIC_TOKEN is the most common: token was already exchanged (double-submit) or expired after 30 minutes.
  Required handlingCaller MUST wrap in try-catch. Failure means the user's bank connection is lost — they must restart the Link flow. Store the access_token only after successful exchange. INVALID_PUBLIC_TOKEN should prompt the user to re-link, not be shown as a generic error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• transactionsSync · api-error

  error
  WhenITEM_ERROR / PRODUCT_NOT_READY (initial transaction pull still pending), ITEM_ERROR / ITEM_LOGIN_REQUIRED (user must re-authenticate), INSTITUTION_ERROR (bank connectivity failure), RATE_LIMIT_EXCEEDED, or network failure.
  ThrowsAxios error with PlaidError in error.response.data. PRODUCT_NOT_READY is common on first call before the initial pull completes. ITEM_LOGIN_REQUIRED requires re-linking via Link update mode.
  Required handlingCaller MUST wrap in try-catch. This is typically called inside a webhook handler — an unhandled error silently breaks transaction sync. Handle PRODUCT_NOT_READY by retrying later; handle ITEM_LOGIN_REQUIRED by notifying the user to re-link their account.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][6]
• accountsGet · api-error

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED (credentials expired or revoked), INSTITUTION_ERROR (bank unavailable), INVALID_INPUT / INVALID_ACCESS_TOKEN, or network failure.
  ThrowsAxios error with PlaidError in error.response.data. ITEM_LOGIN_REQUIRED is the most common production error -- the user's bank session expired and they must re-link.
  Required handlingCaller MUST wrap in try-catch. Surface ITEM_LOGIN_REQUIRED to the user as a prompt to update their bank connection. Other errors should return a 5xx to avoid exposing Plaid internals.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][6]
• authGet · api-error

  error
  WhenITEM_ERROR / PRODUCT_NOT_READY (Auth product not yet initialized), ITEM_ERROR / ITEM_LOGIN_REQUIRED, INVALID_INPUT (institution does not support Auth), or network failure.
  ThrowsAxios error with PlaidError in error.response.data. PRODUCT_NOT_READY means Auth hasn't been initialized yet for this Item. Some institutions require micro-deposit verification.
  Required handlingCaller MUST wrap in try-catch. Auth data is used for financial operations; unhandled errors can cause incorrect routing. Handle PRODUCT_NOT_READY with polling or retry logic. Handle ITEM_LOGIN_REQUIRED by prompting re-link.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8][6]
• transferCreate · api-error

  error
  WhenTRANSFER_ERROR (authorization expired, duplicate transfer, account closed), INVALID_INPUT (invalid account_id or amount), API_ERROR, or network failure. Authorization IDs expire after a short window; using an expired ID returns TRANSFER_ERROR / AUTHORIZATION_EXPIRED.
  ThrowsAxios error with PlaidError in error.response.data. AUTHORIZATION_EXPIRED is common if too much time passes between authorization and creation. DUPLICATE_TRANSFER prevents double-charging.
  Required handlingCaller MUST wrap in try-catch. This is a financial operation -- an unhandled error can result in a silent failure where money was not moved but the app treats it as success. Log error.response.data.request_id for reconciliation. NEVER retry without checking transfer status first.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][2]
• identityGet · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when the user's bank credentials have expired or been revoked. Identity data cannot be refreshed without re-authentication.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. Propagate ITEM_LOGIN_REQUIRED to trigger a re-link flow for the user. KYC verification must not silently proceed with stale or missing identity data.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[10][6]
• identityGet · institution-error

  warning
  WhenINSTITUTION_ERROR / INSTITUTION_DOWN or INSTITUTION_NOT_RESPONDING when the bank is unavailable and identity data cannot be fetched.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'INSTITUTION_ERROR'. Transient -- institution may recover without user action.
  Required handlingCaller MUST wrap in try-catch. Return a 503 to the client; do NOT mark KYC as failed. Queue for retry with backoff.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][10]
• liabilitiesGet · no-liability-accounts

  error
  WhenITEM_ERROR / NO_LIABILITY_ACCOUNTS when the Item has no credit, student loan, PayPal, or mortgage accounts matching the product scope.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'NO_LIABILITY_ACCOUNTS'.
  Required handlingCaller MUST wrap in try-catch. This is a legitimate data absence, not a service failure. Surface a user-friendly message: "No liability accounts found." Do not treat as a generic error.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][11]
• liabilitiesGet · products-not-supported

  error
  WhenITEM_ERROR / PRODUCTS_NOT_SUPPORTED when the financial institution does not support the liabilities product. Common for smaller or international banks.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'PRODUCTS_NOT_SUPPORTED'.
  Required handlingCaller MUST wrap in try-catch. Show user an institution-not-supported message and prompt to connect a different account. Do not retry.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][11]
• liabilitiesGet · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when the user's credentials have expired and liability data cannot be refreshed.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. Trigger re-link flow. Liability data used for underwriting must not be based on stale pre-error snapshots.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6][11]
• investmentsHoldingsGet · no-investment-accounts

  error
  WhenITEM_ERROR / NO_INVESTMENT_ACCOUNTS when the Item has no investment accounts at the institution.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'NO_INVESTMENT_ACCOUNTS'.
  Required handlingCaller MUST wrap in try-catch. Show a user-friendly message; this is a data absence, not a service error. Do not retry.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][12]
• investmentsHoldingsGet · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when credentials have expired and investment holdings data cannot be refreshed.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. Portfolio display must not show stale data without warning. Prompt re-link and flag holdings as potentially outdated.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6][12]
• investmentsTransactionsGet · no-investment-accounts

  error
  WhenITEM_ERROR / NO_INVESTMENT_ACCOUNTS when no investment accounts are available on the Item.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'NO_INVESTMENT_ACCOUNTS'.
  Required handlingCaller MUST wrap in try-catch. Tax reporting features must handle this gracefully; do not attempt to generate empty tax forms on error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][12]
• investmentsTransactionsGet · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when credentials have expired.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. Investment transaction history for tax reporting cannot be incomplete. Prompt re-link immediately.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6][12]
• transactionsGet · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when the user's credentials have expired and transaction data cannot be fetched.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. Transaction pipelines (ETL jobs, background sync) must detect ITEM_LOGIN_REQUIRED and notify the user to re-link, not silently skip the fetch.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6][13]
• transactionsGet · product-not-ready

  warning
  WhenITEM_ERROR / PRODUCT_NOT_READY when the initial transaction pull is still in progress. Common immediately after Item creation.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'PRODUCT_NOT_READY'.
  Required handlingCaller MUST wrap in try-catch. Use webhook (INITIAL_UPDATE, HISTORICAL_UPDATE) to trigger the first call rather than polling. Unhandled PRODUCT_NOT_READY in a sync job crashes the job loop.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][13]
• transactionsRefresh · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when credentials have expired and a fresh pull cannot be initiated.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. A failed refresh means the webhook will never fire. Notify the user to re-link rather than waiting indefinitely for a webhook that won't arrive.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6][13]
• transactionsRefresh · institution-error

  warning
  WhenINSTITUTION_ERROR when the bank is temporarily unavailable and the refresh request cannot be queued.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'INSTITUTION_ERROR'.
  Required handlingCaller MUST wrap in try-catch. Retry with exponential backoff. Do not surface institution errors to the user as permanent failures.
  costlowin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[2][13]
• accountsBalanceGet · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when the institution session has expired. Real-time balance cannot be fetched without valid credentials.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. A balance check failure before a payment MUST halt the payment flow. Do not use stale cached balance as a fallback; it may be outdated by hours or days.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][14]
• accountsBalanceGet · institution-error

  error
  WhenINSTITUTION_ERROR / INSTITUTION_DOWN or INSTITUTION_NOT_RESPONDING when the bank cannot respond in real time. More frequent than with accountsGet since accountsBalanceGet forces a live fetch.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'INSTITUTION_ERROR'.
  Required handlingCaller MUST wrap in try-catch. If checking balance before a payment, fail-safe by blocking the payment rather than proceeding without balance verification. Return a user-friendly retry message.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][14]
• itemGet · item-not-found

  error
  WhenINVALID_INPUT / ITEM_NOT_FOUND when the access_token references a deleted or non-existent Item. Common if the Item was removed via itemRemove but the access token is still stored in the database.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'INVALID_INPUT', error_code = 'ITEM_NOT_FOUND' (or 'INVALID_ACCESS_TOKEN').
  Required handlingCaller MUST wrap in try-catch. ITEM_NOT_FOUND means the stored access_token is stale. Delete the token from the database and prompt the user to relink. Do not treat as a transient error.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[15][2]
• itemRemove · api-error

  error
  WhenINVALID_INPUT / ITEM_NOT_FOUND (token already removed), API_ERROR, or network failure. A failed itemRemove means the Item is NOT removed from Plaid's system and billing continues.
  ThrowsAxios error with PlaidError in error.response.data. ITEM_NOT_FOUND is benign (already removed); API_ERROR should be retried.
  Required handlingCaller MUST wrap in try-catch. Log the request_id for reconciliation. ITEM_NOT_FOUND should be treated as success (idempotent removal). API_ERROR must be retried to stop subscription billing. Only delete the access_token from the database after confirmed removal.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[16][2]
• transferAuthorizationCreate · transfer-account-blocked

  error
  WhenTRANSFER_ERROR / TRANSFER_ACCOUNT_BLOCKED when a previous transfer involving the same end-user account resulted in an error (e.g., NSF, unauthorized return). Plaid blocks the account from future transfers.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'TRANSFER_ERROR', error_code = 'TRANSFER_ACCOUNT_BLOCKED'.
  Required handlingCaller MUST wrap in try-catch. Account is permanently blocked for transfers -- do not retry. Prompt the user to link a different account. This is a risk signal, not a transient error.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17][18]
• transferAuthorizationCreate · transfer-unsupported-account-type

  error
  WhenTRANSFER_ERROR / TRANSFER_UNSUPPORTED_ACCOUNT_TYPE when the account type does not support the requested ACH class (e.g., credit card account selected for an ACH debit).
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'TRANSFER_ERROR', error_code = 'TRANSFER_UNSUPPORTED_ACCOUNT_TYPE'.
  Required handlingCaller MUST wrap in try-catch. Show a clear error: the selected account type does not support this payment method. Ask the user to select a checking or savings account.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17][18]
• transferAuthorizationCreate · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when the user's credentials have expired and the authorization cannot be evaluated.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. Block the payment flow and prompt re-link before retrying the transfer. Authorization cannot proceed without valid credentials.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][18]
• transferGet · api-error

  error
  WhenINVALID_INPUT when the transfer_id is invalid or does not exist in this client's scope, or API_ERROR on Plaid infrastructure failure.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'INVALID_INPUT' or 'API_ERROR'.
  Required handlingCaller MUST wrap in try-catch. A failed transferGet should trigger a retry with backoff -- the transfer may still exist and be processing. Do not assume a failed GET means the transfer failed.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[18][2]
• signalEvaluate · signal-error

  error
  WhenSIGNAL_ERROR / INVALID_ACCOUNT_ID when the account has been removed or the account_id is no longer valid. Also ITEM_LOGIN_REQUIRED when bank data cannot be accessed.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'SIGNAL_ERROR', error_code = 'INVALID_ACCOUNT_ID' or error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. A failed signal evaluation means risk cannot be assessed. Fail-safe by blocking the transfer rather than proceeding without a risk score. Log the request_id.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[19][2]
• itemWebhookUpdate · api-error

  warning
  WhenINVALID_INPUT (invalid webhook URL format or HTTPS requirement not met), ITEM_ERROR / ITEM_NOT_FOUND (stale access_token), or API_ERROR.
  ThrowsAxios error with PlaidError in error.response.data. Webhook URLs must be HTTPS; HTTP URLs are rejected with INVALID_INPUT.
  Required handlingCaller MUST wrap in try-catch. A failed webhook update means future transaction events won't reach the application. Verify webhook URL is HTTPS and retry on API_ERROR.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[20][2]
• transactionsRecurringGet · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when the user's credentials have expired and recurring transaction analysis cannot be refreshed.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. Recurring transaction data used for bill prediction must not be stale. Surface re-link prompt.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6][13]
• transactionsRecurringGet · product-not-ready

  warning
  WhenITEM_ERROR / PRODUCT_NOT_READY when the transactions product has not yet completed its initial pull for this Item.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'PRODUCT_NOT_READY'.
  Required handlingCaller MUST wrap in try-catch. Wait for HISTORICAL_UPDATE webhook before calling this endpoint. Show a loading state to the user.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][13]
• assetReportCreate · asset-report-creation-error

  error
  WhenASSET_REPORT_ERROR (PRODUCT_NOT_ENABLED, NO_AUTH_ACCOUNTS, INVALID_PARENT, DATA_UNAVAILABLE) or per-Item ITEM_ERROR returned as causes[] entries. One access_token in the batch failing surfaces as a top-level error with a non-empty causes[] array — partial reports are NOT created.
  ThrowsAxios error. Access PlaidError via error.response.data. Fields: error_type = 'ASSET_REPORT_ERROR', error_code (e.g. 'PRODUCT_NOT_ENABLED', 'NO_AUTH_ACCOUNTS', 'DATA_UNAVAILABLE'), causes[] (per-Item breakdown when multiple access_tokens were passed).
  Required handlingCaller MUST wrap in try-catch. Asset Report creation is the gating step for the entire lending verification flow — a silent failure here blocks loan applications. Inspect causes[] when batching multiple Items; you may need to re-link a single Item without aborting the whole report. Do NOT log the full error (request headers contain client_secret).
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21][22]
• assetReportCreate · invalid-input-error

  error
  WhenINVALID_INPUT when access_token is malformed/expired/revoked, when days_requested exceeds tier maximum (e.g. >730), or when options.user fields are missing required attributes for downstream consumers (Fannie Mae / Freddie Mac require specific user fields).
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'INVALID_INPUT', error_code (e.g. 'INVALID_ACCESS_TOKEN', 'INVALID_FIELD', 'TOO_MANY_VERIFICATION_ATTEMPTS').
  Required handlingCaller MUST wrap in try-catch. INVALID_INPUT is a programmer error — fix the request rather than retrying. Validate access_token format and days_requested ceiling client-side before calling.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[4]
• assetReportCreate · rate-limit-exceeded

  warning
  WhenRATE_LIMIT_EXCEEDED when Asset Report creation rate exceeds tier limits. Particularly common in batch onboarding flows where hundreds of reports are generated in a short window (lender bulk-uploads, refinance bursts).
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'RATE_LIMIT_EXCEEDED', error_code = 'RATE_LIMIT'.
  Required handlingCaller MUST wrap in try-catch and implement exponential backoff with jitter. Asset Report creation is expensive — gate batch jobs at a known-safe RPS. Surface a delay banner to the user, NOT a hard error.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[23]
• identityVerificationCreate · invalid-input-error

  error
  WhenINVALID_INPUT when template_id is missing/unknown, client_user_id is invalid, or required user fields (e.g. email_address, phone_number) are missing for the chosen template. Common when a template requires SSN but the request omits it.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'INVALID_INPUT', error_code (e.g. 'INVALID_FIELD', 'INVALID_TEMPLATE', 'MISSING_FIELDS').
  Required handlingCaller MUST wrap in try-catch. Identity verification is a gating step for account opening — failure here means the user cannot proceed. Validate template requirements server-side and surface a clear actionable error to the user.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24][4]
• identityVerificationCreate · idempotent-conflict

  error
  WhenINVALID_REQUEST / IDV_INVALID_TEMPLATE_OR_VERSION when the (client_user_id, template_id) pair already has an active verification and is_shareable is false. Plaid blocks duplicate sessions for the same user against the same template to prevent abuse and duplicate billing.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'INVALID_REQUEST', error_code references the existing identity_verification_id in error_message.
  Required handlingCaller MUST wrap in try-catch. On this error, fetch the existing verification via identityVerificationGet using the id surfaced in error_message rather than retrying create. Do NOT show a generic "verification failed" — the user already has a session.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[24]
• identityVerificationCreate · api-error

  error
  WhenAPI_ERROR (Plaid-side outage) or INSTITUTION_ERROR (downstream KYC provider unavailable). Document-verification flows depend on third-party OCR/document providers which can have independent outages.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'API_ERROR' or 'INSTITUTION_ERROR'.
  Required handlingCaller MUST wrap in try-catch. Implement retry with exponential backoff for API_ERROR (transient). For INSTITUTION_ERROR, allow the user to retry but surface a degraded-state message rather than blocking.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[25]
• processorTokenCreate · invalid-account-id

  error
  WhenINVALID_INPUT / INVALID_ACCOUNT_ID when account_id does not belong to the Item identified by access_token, or when the account has been closed/removed at the institution. Also fires when processor name is not one of the supported enum values (e.g. typo'd 'stripe' as 'strype').
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'INVALID_INPUT', error_code = 'INVALID_ACCOUNT_ID' or 'INVALID_FIELD' for processor enum mismatch.
  Required handlingCaller MUST wrap in try-catch. The processor_token is the prerequisite for ANY payment flow — silent failure here means the user clicks "Pay" and nothing happens. Surface a re-link prompt for closed accounts.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[26][4]
• processorTokenCreate · item-login-required

  error
  WhenITEM_ERROR / ITEM_LOGIN_REQUIRED when the user's credentials at the institution have expired/been revoked. processorTokenCreate requires a healthy Item; cannot mint a processor_token from a broken one.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'ITEM_ERROR', error_code = 'ITEM_LOGIN_REQUIRED'.
  Required handlingCaller MUST wrap in try-catch. Trigger Link in update mode to refresh credentials, then retry processorTokenCreate. Do NOT proceed with the payment flow against a stale processor_token.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][27]
• processorTokenCreate · rate-limit-exceeded

  warning
  WhenRATE_LIMIT_EXCEEDED when processor token creation rate exceeds tier limits. Particularly common in batch reconciliation flows where many processor tokens are refreshed in sequence.
  ThrowsAxios error with PlaidError in error.response.data. error_type = 'RATE_LIMIT_EXCEEDED', error_code = 'RATE_LIMIT'.
  Required handlingCaller MUST wrap in try-catch and implement exponential backoff. Pace batch processor-token refresh below the documented tier RPS.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[23]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.