> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Digital Wallet Token Lifecycle Errors

> Understand why a digital wallet token's state on the Marqeta platform can differ from its state with the token service provider, and how to resolve the 422003 and 422004 error codes on activate, suspend, and terminate requests.

<h2 id="_overview">
  Overview
</h2>

When you send an activate, suspend, or terminate request for a digital wallet token (DWT), Marqeta forwards the request to the token service provider (TSP).
If the TSP's response is ambiguous — for example, it reports the token as not found or the request data as invalid — Marqeta checks with the TSP directly for the token's actual state before responding to you.
This check can surface a mismatch between the token's state on record with Marqeta and its actual state with the TSP, which Marqeta reports using the `422003` and `422004` error codes on `POST /digitalwallettokentransitions`.

This article explains why that mismatch can occur and what to do about it.
For the field-level error reference and sample response bodies, see [Digital Wallets Management](/docs/core-api/digital-wallets-management).

<h2 id="_why_the_marqeta_and_tsp_states_can_differ">
  Why the Marqeta and TSP states can differ
</h2>

A token's state on record with Marqeta can fall out of sync with its actual state on the TSP.
This can happen if a TSP notification confirming a change is delayed or never reaches Marqeta, if a request to the TSP times out and Marqeta can't confirm whether it was processed, or if the token's state changes directly on the TSP outside of a Marqeta-initiated call.

<h2 id="_resolution_by_scenario">
  Resolution by scenario
</h2>

The following tables summarize each scenario, the response you receive, and what you need to do.

<h3 id="_terminate">
  Terminate
</h3>

| Field               | Value                                                                 |
| ------------------- | --------------------------------------------------------------------- |
| Marqeta state       | `REQUESTED`, `ACTIVE`, or `SUSPENDED`                                 |
| TSP state           | `NOT_FOUND`, `INVALID_DATA`, `REQUIRED_DATA_MISSING`, or `TERMINATED` |
| Response            | `201`                                                                 |
| What you need to do | None. The token is confirmed terminated.                              |

<h3 id="_activate">
  Activate
</h3>

| Field               | Value                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Marqeta state       | `REQUESTED` or `SUSPENDED`                                                                                                                                   |
| TSP state           | `NOT_FOUND`, `INVALID_DATA`, `REQUIRED_DATA_MISSING`, or `TERMINATED`                                                                                        |
| Response            | `422004`                                                                                                                                                     |
| What you need to do | Transition the token's state to match the TSP state in `error_message`. If the TSP state is one of the four listed here, transition the token to terminated. |

<h3 id="_suspend">
  Suspend
</h3>

| Field               | Value                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Marqeta state       | `ACTIVE`                                                                                                                                                     |
| TSP state           | `NOT_FOUND`, `INVALID_DATA`, `REQUIRED_DATA_MISSING`, or `TERMINATED`                                                                                        |
| Response            | `422004`                                                                                                                                                     |
| What you need to do | Transition the token's state to match the TSP state in `error_message`. If the TSP state is one of the four listed here, transition the token to terminated. |

<Note>
  * For any other `422003` error not covered by the scenarios above, the failure is a generic TSP error.
    Retry the request later; if the error persists, contact Marqeta support.
  * Marqeta blocks any state transition request (activate, suspend, or terminate) against a token that's already `TERMINATED`.
    This guidance covers TSP-related errors (`422003`/`422004`) only — a request against an already-terminated token returns a separate validation error.
</Note>

This guidance applies to both Visa Token Service (VTS) and Mastercard Digital Enablement Service (MDES) token paths.

For more information, see [Digital Wallets Management](/docs/core-api/digital-wallets-management), [Errors](/docs/core-api/errors), and [Managing the Digital Wallet Token Lifecycle](/docs/developer-guides/managing-the-digital-wallet-token-lifecycle).