Typed Plaid error struct with retry classification, suggested actions, and structured metadata for logging and observability.

Every error that can come from Plaid is classified into:

• An error_type matching Plaid's taxonomy
• A suggested_action for your application code
• A retryable flag for the HTTP client's retry logic

Plaid error taxonomy

Plaid categorises errors into these types (from their API reference):

• INVALID_REQUEST — malformed request parameters
• INVALID_RESULT — Plaid returned an unexpected result
• INVALID_INPUT — semantically invalid input (e.g., wrong access token)
• INSTITUTION_ERROR — institution outage, timeout, or maintenance
• RATE_LIMIT_EXCEEDED — API rate limit hit
• API_ERROR — Plaid internal error
• ITEM_ERROR — item-level errors (login required, no accounts, etc.)
• ASSET_REPORT_ERROR — asset report specific errors
• RECAPTCHA_ERROR — CAPTCHA challenge required
• OAUTH_ERROR — OAuth flow errors
• PAYMENT_ERROR — payment initiation errors
• BANK_TRANSFER_ERROR — bank transfer errors
• INCOME_VERIFICATION_ERROR — income verification errors
• MICRODEPOSITS_ERROR — micro-deposit verification errors

Handling errors

case PlaidEx.API.Transactions.sync(config, access_token: token) do
  {:ok, page} ->
    process(page)

  {:error, %PlaidEx.Error{code: "ITEM_LOGIN_REQUIRED"}} ->
    # Send user back through Link to reconnect
    redirect_to_link_update_mode(item_id)

  {:error, %PlaidEx.Error{retryable: true} = error} ->
    # Safe to retry after delay
    schedule_retry(error)

  {:error, %PlaidEx.Error{} = error} ->
    # Non-retryable — needs human attention
    alert_on_call(error)
end