Handling Update Failures

Common Failure Modes

Direct Updates can fail for several reasons. In the Update response, direct retrieval failures currently surface through a canonical error object:

Failure Mode	Where it surfaces	Recommended Action
Institution unreachable or temporarily unavailable	Update `error.code: 21001`; account `data_status_error` is usually `15004` or `15006`.	Retry after a delay. These are usually transient.
Account not supported	Account `data_status_error: 15009`.	Check the account’s `products` array, then rely on snapshot Updates from an `update.snapshot` subscription.
Account closed, paid off, transferred, or consolidated	Account `data_status_error` is `15001`, `15002`, `15003`, or `15010`.	Update your local records. Re-discover via Connect when appropriate.
Authentication or account detail mismatch	Account `data_status_error` is `15005` or `15007`.	Refresh identity or account details, then re-enroll or re-discover the account.
Delinquent or disabled liability	Account `data_status_error` is `15008` or `15011`.	Surface the state to the user or contact support if unexpected.

{
  "id": "upt_NYV5kfjskTTCJ",
  "status": "failed",
  "error": {
    "type": "UPDATE_FAILED",
    "sub_type": "UPDATE_TEMPORARILY_UNAVAILABLE",
    "code": 21001,
    "message": "Update is temporarily unavailable for this account."
  }
}

For the granular reason, read the underlying account liability’s data_status_error. These are the codes exposed by the API:

Code	Reason	What it means	Recommended action
`15001`	Closed	The account has been closed at the institution.	Update your local records. Don’t retry.
`15002`	Paid in full	The liability has been paid off.	Update your local records. Don’t retry.
`15003`	No longer serviced	The institution no longer services this account (e.g. transferred or sold).	Update your local records. Don’t retry.
`15004`	Unauthorized / sync failed	Catch-all for transient and connection-level failures (institution timeouts, technical issues, outside-hours, internal errors, repeated failure throttling).	Retry after a delay. If persistent, contact support.
`15005`	Invalid holder details	The institution rejected the holder details Method has on file (e.g., DOB, postal code, KYC).	Refresh the entity’s identity data and re-enroll.
`15006`	Temporarily unavailable	Generic temporary failure.	Retry after a delay.
`15007`	Invalid account number	The account number Method has is no longer valid at the institution.	Re-discover the account via Connect.
`15008`	Delinquent	The account is in a delinquent state at the institution.	Surface this to the user. Don’t retry until resolved.
`15009`	Unsupported merchant	The institution doesn’t support real-time data connections for this account type.	Rely on snapshot Updates delivered via an `update.snapshot` subscription.
`15010`	Consolidated loan	The student loan has been consolidated into a different loan.	Re-discover via Connect.
`15011`	Liability disabled	Updates have been disabled for this liability.	Don’t retry. Contact support if unexpected.

Rate limiting is not currently exposed as a distinct Update failure code. Repeated failure throttling may appear under the catch-all sync failed reason (15004).

Retry Strategy

First retry: wait 5 minutes
Second retry: wait 30 minutes
Third retry: wait 2 hours
After 3 failures: display the most recent snapshot data and alert your CSM

Use idempotency keys when retrying to avoid duplicate requests.

Fallback Pattern: Direct to Snapshot

When direct Updates aren’t available or keep failing, snapshot data provides a reliable baseline. Note that POST /accounts/{acc_id}/updates always creates a direct Update; you cannot request a snapshot Update on demand. Snapshot Updates are produced by update.snapshot subscriptions and delivered via webhook. To fall back to snapshot data, list the account’s existing Updates and use the most recent one whose source is snapshot:

curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates?source=snapshot" \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"

If no snapshot Update exists yet, create an update.snapshot subscription so future bureau refreshes are delivered automatically:

curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{"type": "update.snapshot"}'

UX Recommendations

Always show the most recent known data, even if it’s stale. A balance from last week is better than a blank screen.
Indicate freshness. Show the data_as_of timestamp so users know how current the data is: “Balance as of March 20, 2024.”
Show refresh state. When an Update is in progress, show a loading indicator alongside the existing data.
Don’t block on failures. If a direct Update fails, display the last snapshot data and retry in the background.

Subscription Failures

For failed subscription executions, Method requeues the subscription execution for retry. The subscription queue retries failed executions daily up to three times, then schedules the next run according to the subscription’s normal cadence. Monitor update.update webhooks for failed Updates to detect persistent issues with specific accounts or institutions and to drive your own fallback (e.g., showing snapshot data, prompting the user to reconnect for 15005/15007).

Fields by Liability Type

The data returned in an Update depends on the account type. Common patterns:

Liability Type	Key Fields
Credit Card	balance, available_credit, credit_limit, interest_rate (min/max/type), payment info, opened_at
Auto Loan	balance, interest_rate, original_loan_amount, term_length, expected_payoff_date, payment info
Student Loan	balance, original_loan_amount, term_length, payment info
Mortgage	balance, interest_rate, original_loan_amount, term_length, expected_payoff_date, payment info
Personal Loan	balance, available_credit, interest_rate, original_loan_amount, term_length, payment info

All types share: balance, last_payment_amount, last_payment_date, next_payment_due_date, next_payment_minimum_amount, opened_at, closed_at. For the full Updates API, see the Updates reference.

Getting Started

Entities

Identity Verification

Connect

Accounts

Updates

Payments

Additional Products

Use Cases: Commerce

Use Cases: Lending

Use Cases: PFM

Common Failure Modes

Retry Strategy

Fallback Pattern: Direct to Snapshot

UX Recommendations

Subscription Failures

Fields by Liability Type

​Common Failure Modes

​Retry Strategy

​Fallback Pattern: Direct to Snapshot

​UX Recommendations

​Subscription Failures

​Fields by Liability Type

Common Failure Modes

Retry Strategy

Fallback Pattern: Direct to Snapshot

UX Recommendations

Subscription Failures

Fields by Liability Type