# New token refusals in 3.2

Source: https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2-refusals
Each DALP 3.2 token operation that keeps its shape but refuses a request 3.1 accepted, or refuses with a different code: what changed and what to do.

This page lists every token operation that refuses differently in DALP 3.2 (mints, burns, transfers, yield claims, fees, and prices). For platform-level refusals (list queries, audit trail, maker-checker, templates, documents, external tokens, compliance roles, and wallet factors), see [New platform refusals in 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2-refusals-platform). For schema and SDK changes, see [Upgrade an integration to 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2).

## New refusals on existing operations [#new-refusals-on-existing-operations]

These operations keep their 3.1 request and response shapes but reject requests 3.1 accepted or return new error codes. Generated clients do not flag them at compile time.

### Gas refusals [#gas-refusals]

**What changed.** Token writes refused because the paying account lacks gas now return `400` `TRANSACTION_QUEUE_FUNDING_REQUIRED` (`DALP-14062`, `data.refusal: "FundingRequired"`, non-retryable), with `data.transactionId` when recorded. This covers direct token and token-feature writes, token role changes, synchronous token creates and price updates, and coordinated corporate-action preview, confirm, abort, and leg release steps.

When a self-paying smart wallet lacks gas, DALP returns `422` `TRANSACTION_QUEUE_SMART_WALLET_GAS_REQUIRED` (`DALP-14034`) with `smartWalletAddress` and `shortfallWei` in `data`.

**Who is affected.** Clients performing token writes, role updates, price updates, or coordinated corporate actions.

**How to detect it.** Writes return `400` with `data.refusal: "FundingRequired"` or `422` with `DALP-14034`.

**What to do.** Fund the paying account before retrying. Do not auto-retry `DALP-14062`. If a retry returns `TRANSACTION_QUEUE_DUPLICATE_SETTLED` (`DALP-14066`), inspect the original transaction and resend under a new `Idempotency-Key`. See [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling#funding-and-custody-failures).

### Bundler wallet without a fee quote [#bundler-wallet-without-a-fee-quote]

**What changed.** `POST /api/v2/organizations/networks/bundler` now sizes funding from the network's live fee quote. If no fresh fee quote exists or the funding request cannot be recorded, it returns `503` (`DALP-12250`, retryable) instead of `200` with `funding: "unknown"`.

**Who is affected.** Clients creating or repairing a bundler wallet and treating `funding: "unknown"` as success.

**How to detect it.** The call returns `503` instead of `200`.

**What to do.** Retry after a short delay. The operation reuses the existing bundler wallet.

### Mint and burn during a corporate action [#mint-and-burn-during-a-corporate-action]

**What changed.** Mints and burns on an asset are refused with `409` `CORPORATE_ACTION_IN_FLIGHT` (`DALP-12067`) while a corporate action run is in flight on that asset, from start until completion or abort. `data.corporateActionId` identifies the active run.

**Who is affected.** Every client that mints or burns, even when another operator started the corporate action.

**How to detect it.** Mint or burn calls return `409` `CORPORATE_ACTION_IN_FLIGHT`.

**What to do.** Wait for the run in `data.corporateActionId` to complete, or abort it, then resend the mint or burn. See [Corporate actions](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions).

### Burns and forced transfers on a frozen address [#burns-and-forced-transfers-on-a-frozen-address]

**What changed.** Assets on the DALP 3.2 token contract now refuse burns from a fully frozen address with `DALP-1076` ("Sender address frozen") and forced transfers into one with `DALP-1074` ("Recipient address frozen"). Multi-holder requests fail as a whole if any named address is frozen. Partial balance freezes do not block either operation.

Template-issued assets move to the 3.2 token contract when the organisation runs [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates). Assets from the seven original factories keep 3.1 behaviour, though the API still blocks [maturity redemptions from a frozen holder](#maturity-redemptions-by-a-frozen-holder) on every asset.

**Who is affected.** Clients calling `POST /api/v2/tokens/{assetId}/burns` or `POST /api/v2/tokens/{assetId}/forced-transfers` on potentially frozen addresses.

**How to detect it.** Because the API does not pre-check address freezes on these routes, async writes return `202 Accepted` and end `FAILED` with `contractError.id` `DALP-1076` or `DALP-1074`. Calls with `Prefer: wait` return `422` `CONTRACT_ERROR` with that `data.id`.

**What to do.** Check `data.holder.balance.isFrozen` via `GET /api/v2/tokens/{assetId}/holder-balances?holderAddress={address}` first. Lift the freeze with `PUT /api/v2/tokens/{assetId}/address-freezes` (`freeze: false`), or forced-transfer from the frozen sender to an eligible wallet and burn there.

### Burns that name a restricted wallet [#burns-that-name-a-restricted-wallet]

**What changed.** DALP 3.2 introduces [wallet restrictions](https://docs.settlemint.com/docs/console/participants/restricted-wallet-burns#burns-and-corporate-actions). Operations targeting restricted wallets behave by operation type:

| Operation | 3.2 behaviour for restricted wallets |
| --- | --- |
| `POST /api/v2/tokens/{assetId}/burns` and burn preflights | Skips restricted wallets (system restriction or [wallet restriction module](https://docs.settlemint.com/docs/console/participants/restricted-wallet-on-chain#the-wallet-restriction-module)), burns remaining wallets, and returns omitted addresses in optional `skipped` (on `200` and `202`). Refuses with `409` `TOKEN_ADDRESS_RESTRICTION_ACTIVE` (`DALP-9590`) if every wallet is restricted. |
| v1 burn | Refuses the entire request with a v1 `400` bad request naming the restricted wallet. |
| Buyback and partial redemption confirm | Omits restricted holders with `skipReason: "restricted"`. Returns `409` `DALP-9590` if no holder remains. |
| Reverse split, capital decrease, and rights close | On 3.2 token contracts, burns restricted holders in place via `batchForcedBurn` when executed by a smart wallet holding both `custodian` and `supplyManagement`. Otherwise skips them (`409` `DALP-9590` if no holder remains on reverse split or capital decrease, while rights close never returns `409`). Reverse splits withhold cash in lieu in optional `cashOwed`. Older contracts use plain burn as in 3.1. |
| Minting corporate actions | Omits frozen addresses with `skipReason: "restricted"` (if restricted) or `"frozen"`, minting to remaining holders instead of failing on chain. |
| Forced transfers | Allowed. Adds optional `restrictedSenders` to the response. |
| Forced conversions (`POST /api/v2/tokens/{assetId}/features/conversion-minter/forced-conversions`) | Refuses with `409` `TOKEN_ADDRESS_RESTRICTION_ACTIVE` (`DALP-9590`) when the holder has an active restriction in the asset's system or on the wallet restriction module. Refuses before checking `walletVerification`, under every debt method. |

**Who is affected.** Clients that burn, force-transfer, force-convert, confirm corporate actions, or settle fund redemptions in any organisation using wallet restrictions or sharing a system with the wallet restriction module.

**How to detect it.** Burn responses (`200` or `202`) include `skipped`, or return `409` `TOKEN_ADDRESS_RESTRICTION_ACTIVE` (`DALP-9590`). Buyback, partial redemption, reverse split, capital decrease, and forced conversion calls return the same `409` `DALP-9590` when refused. Corporate action holders carry `skipReason` (`"restricted"` or `"frozen"`) or `cashOwed`.

**What to do.** Read `skipped` on every burn response and book only settled pairs. Update strict decoders to accept optional `skipped`, `restrictedSenders`, `cashOwed`, `skipReason` values `restricted` and `frozen`, and entries or `DALP-9590` refusals (for burns, forced conversions, and corporate-action confirms) without `restrictionId` (omitted for other organisations' restrictions, module-only restrictions, or callers lacking owner, admin, `complianceManager`, or `custodian` access).

When a forced conversion returns `DALP-9590`, send it again after the holder's restriction is lifted while the trigger is active and the conversion window stays open.

To burn restricted holders in place during reverse splits, capital decreases, or rights closes, execute from a smart wallet with both `custodian` and `supplyManagement`. Raise at most one follow-up per run (a second returns `409` `CORPORATE_ACTION_FOLLOW_UP_UNKNOWN`, `DALP-12069`). After a restriction lift or unfreeze, run a follow-up for any `skipReason: "restricted"`, `skipReason: "frozen"`, or unpaid `cashOwed` entry. See [Restricted holders](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#restricted-holders).

### The wallet restriction module [#the-wallet-restriction-module]

**What changed.** DALP 3.2 adds the system-wide `wallet-restriction` compliance module type, which blocks transfers from restricted wallets across every token in the system and blocks ordinary burns on 3.2 token contracts. Forced transfers and forced burns still bypass compliance modules.

The platform installs it automatically on new systems and during [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates#the-wallet-restriction-row) on existing systems (loading all active restricted wallets). Until installed, transfers and burns keep 3.1 behaviour.

| Surface | 3.2 change |
| --- | --- |
| `ComplianceTypeId` and reads | Adds `wallet-restriction`. Returned by `GET /api/v2/system/compliance-modules` and token module reads once registered. |
| `POST /api/v2/tokens` | `initialModulePairs[].typeId` uses `TokenComplianceTypeId` and refuses `wallet-restriction` with `400` `REQUEST_INVALID`. |
| Manual module install routes | `POST /api/v2/system/compliance-modules/configure` (without `instanceAddress`), `.../scoped`, `POST /api/v2/tokens/{assetId}/compliance-modules`, and `.../scoped` refuse `wallet-restriction` with `409` `compliance.module.STATE_INVALID` (`DALP-12285`, `data.reason: "system-installed-only"`). v1 returns `409` `CONFLICT` (`DALP-12285`). `POST /api/v2/system/compliance-modules/scope` still scopes an installed module. |
| `GET /api/v2/system/migration-comparison` | May return component `WALLET_RESTRICTION` with optional `walletRestriction` (`moduleInstalled`, `walletsMissing`) and `notFullyEnforced` (`reason`: `disabled` or `scoped`). Counts in `summary.needUpgrade` only while `outstanding` is above `0`. |
| Transfers from a restricted wallet | Frozen on the token: refused pre-queue with `422` `CONTRACT_ERROR` (`DALP-1076`). Not frozen on the token: queued and ends `FAILED` with `contractError.id` `DALP-1120` (`COMPLIANCE_CHECK_REASON_WALLET_RESTRICTED`), or `422` `CONTRACT_ERROR` with `Prefer: wait`. |

**Who is affected.** Clients creating wallet restrictions, transferring or burning from restricted wallets, decoding `ComplianceTypeId`, or installing compliance modules by type.

**How to detect it.** Installs return `409` with `data.reason: "system-installed-only"`, module reads include `wallet-restriction`, and transfers fail with `DALP-1076` or `DALP-1120`.

**What to do.** Accept `wallet-restriction` in decoders and exclude it from install and token-create requests. Treat `DALP-1120` (`COMPLIANCE_CHECK_REASON_WALLET_RESTRICTED`) as a module block. Do not rely on `GET /api/v2/restrictions` alone because non-compliance callers get an empty list and direct module restrictions have no DALP restriction record. In an emergency, a Compliance manager can disable the module via `POST /api/v2/system/compliance-module-instances/{instanceAddress}/transitions` (preserves wallets) or remove it via `DELETE /api/v2/system/compliance-modules` (drops wallets until the next System update). See [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls#the-wallet-restriction-rule).

### Settlements a restricted wallet delivers in [#settlements-a-restricted-wallet-delivers-in]

**What changed.** An active wallet restriction holds open positions where the restricted wallet delivers a covered token until the restriction is lifted or a position release is approved.

| Flow | 3.2 behaviour while held |
| --- | --- |
| XvP v2 (`.../executions`, `.../approvals`, `.../secret-revelations`) | Returns `409` `XVP_POSITION_HELD_BY_RESTRICTION` (`DALP-211172`) to every caller including counterparties, with `data.restrictionId` and `data.positionId` (restrictions from any organisation whose system created the settlement apply). |
| `POST /api/v2/transaction-preparations` and finalisation | Returns the same `409` `DALP-211172` for `execute()`, `approve()`, or `revealSecret(bytes)` targeting a held settlement, leaving the preparation intact until release or expiry. |
| XvP v1 execute, approve, and reveal | Returns existing `422` precondition refusal (`DALP-12324`). |
| Trading venue fills and bank rail cash-outs | Venue fills park with reason `wallet-restriction` and cash-outs stay locked without returning a client error. |

**Who is affected.** Clients executing, approving, or revealing XvP settlements (directly or via transaction preparations) and workflows tracking venue fills or cash-outs.

**How to detect it.** XvP and transaction-preparation calls return `409` `DALP-211172` (v1 returns `422` `DALP-12324`), and venue fills remain parked with reason `wallet-restriction`.

**What to do.** Do not retry unchanged. Lift the restriction, or have a Compliance manager [request a position release](https://docs.settlemint.com/docs/console/participants/held-positions#request-the-release-of-a-held-position) approved by a second user, then retry. Cancelling and post-expiry withdrawal remain allowed, and parked venue fills or held cash-outs resume automatically once released.

### Maturity redemptions by a frozen holder [#maturity-redemptions-by-a-frozen-holder]

**What changed.** `POST /api/v2/tokens/{assetId}/features/maturity-redemption/redemptions` now refuses redemptions for a fully frozen signing holder before queueing, returning `422` `CONTRACT_ERROR` with `DALP-1076` ("Sender address frozen") on every token contract. Partial balance freezes do not block redeeming unfrozen units (3.2 contracts protect frozen units, while 3.1 contracts still draw them down).

**Who is affected.** Clients redeeming matured units on behalf of holders.

**How to detect it.** Redemptions return `422` `CONTRACT_ERROR` (`DALP-1076`) instead of `202` or `200`. Validation runs in order: `walletVerification`, pause state, address freeze, then maturity, so a frozen holder gets `DALP-1076` even before maturity.

Because the pre-check reads indexed state, a redemption sent before a freeze is indexed reaches the chain:

- On 3.2 token contracts, the chain reverts it: queued calls end `FAILED` with `contractError.id` `DALP-1076`, while `Prefer: wait` or holder-signed calls return `409` `MATURITY_REDEMPTION_UNAVAILABLE` (`DALP-12373`).
- On 3.1 token contracts, redemptions that reach the chain still burn frozen units and pay out.

**What to do.** Handle `DALP-1076` and check `data.holder.balance.isFrozen` on `GET /api/v2/tokens/{assetId}/holder-balances?holderAddress={address}` before redeeming. After lifting the freeze with `PUT /api/v2/tokens/{assetId}/address-freezes`, wait until `isFrozen` reads `false` before retrying.

### Mints and transfers refused before they are queued [#mints-and-transfers-refused-before-they-are-queued]

**What changed.** `POST /api/v2/tokens/{assetId}/mints`, `POST /api/v2/tokens/{assetId}/transfers`, and `POST /api/v2/tokens/{assetId}/preflights` (`mint` and `transfer`) now refuse five invalid writes before queueing. All five are non-retryable and checked after `walletVerification` on writes. Preflights need no `walletVerification` and return `data.clears: true` when passing:

| Condition | HTTP status and code | `data` details |
| --- | --- | --- |
| Mint or transfer to a fully frozen recipient | `422` `CONTRACT_ERROR` (`DALP-1074`) | "Recipient address frozen" |
| Transfer from a fully frozen sender (checked before balance) | `422` `CONTRACT_ERROR` (`DALP-1076`) | "Sender address frozen" |
| Transfer to an unregistered recipient | `422` `CONTRACT_ERROR` (`DALP-1096`) | `data.args.reason: "identity-not-registered"` |
| Mint exceeding the token's supply cap (compliance limits stay on-chain only) | `422` `CONTRACT_ERROR` (`DALP-4082`) | `data.args.newSupply`, `data.args.cap` |
| Mint overflowing uint256 supply (`2^256 - 1` base units) | `409` `TOKEN_MINT_SUPPLY_OVERFLOW` (`DALP-214341`) | `data.headroom` (v1 returns `400` `BAD_REQUEST`) |

Checks read indexed chain state: unindexed freezes or mints still revert on chain (`FAILED` with the same `contractError.id`), and recently lifted freezes, new registrations, or raised caps can be refused until indexed. Assets using Booked movements, Canton instruments, burns, and forced transfers skip these pre-checks.

**Who is affected.** Clients that mint or transfer, or wait for `FAILED` transactions to detect these conditions.

**How to detect it.** Writes return `422` `CONTRACT_ERROR` or `409` `TOKEN_MINT_SUPPLY_OVERFLOW` immediately without queueing.

**What to do.** Handle all five codes on the write response while retaining `contractError.id` handling on `FAILED` transactions. Use `POST /api/v2/tokens/{assetId}/preflights` before prompting for a PIN. Unfreeze via `PUT /api/v2/tokens/{assetId}/address-freezes` (or lift a wallet restriction if it returns `409` `TOKEN_ADDRESS_RESTRICTION_ACTIVE`), register unregistered recipients, or reduce the mint amount to fit `data.args.cap` or `data.headroom`.

### Amounts in transfers, forced transfers and burns [#amounts-in-transfers-forced-transfers-and-burns]

**What changed.** Every `transfers[].amount` in `POST /api/v2/tokens/{assetId}/transfers` and `POST /api/v2/tokens/{assetId}/forced-transfers`, every `amounts` entry in `POST /api/v2/tokens/{assetId}/burns`, and matching `preflights` actions now require a positive integer of base units up to `2^256 - 1`. Zero, negative numbers, decimals, exponent notation, and larger values return `400` `REQUEST_INVALID` naming the field (for example, `transfers.0.amount`). Mints continue to refuse zero with `400` `TOKEN_MINT_AMOUNT_INVALID` (`DALP-9484`).

**Who is affected.** Clients sending zero, fractional, or scientific-notation amounts to transfers, forced transfers, or burns.

**How to detect it.** Requests return `400` `REQUEST_INVALID` with the amount field in `data.errors`.

**What to do.** Omit zero-amount entries and format every amount as a positive integer string in plain digits.

### Yield claims on a frozen address [#yield-claims-on-a-frozen-address]

**What changed.** Interest claims and fixed-yield coupon claims now refuse a fully frozen holder address with `DALP-9295` (matching dividend claims). Lost-wallet recovery claims are refused while either the lost wallet or replacement wallet is fully frozen. Interest and coupons continue accruing while frozen and pay out after unfreezing. Partial freezes do not block claims.

**Who is affected.** Clients calling `POST /api/v2/tokens/{assetId}/features/interest-yield/claims`, `POST /api/v2/tokens/{assetId}/features/fixed-treasury-yield/claims`, or their `recovered-wallet-claims` routes.

**How to detect it.** Queued claims end `FAILED` with `contractError.id` `DALP-9295`, or return `422` `CONTRACT_ERROR` (`DALP-9295`) with `Prefer: wait`.

**What to do.** Check `data.holder.balance.isFrozen` via `GET /api/v2/tokens/{assetId}/holder-balances?holderAddress={address}` first and claim after lifting the freeze.

### Fee recipient changes [#fee-recipient-changes]

**What changed.** On the DALP 3.2 management fee feature (activated by [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates)), `PATCH /api/v2/tokens/{assetId}/features/aum-fee` pays accrued fees to the old recipient before switching recipients. The update fails without changing the recipient if the asset is halted (`DALP-1109`), the old recipient is frozen (`DALP-1074`), or the old recipient fails compliance (`DALP-1110`).

**Who is affected.** Clients updating a management fee recipient.

**How to detect it.** Async requests return `202 Accepted` and end `FAILED` with `DALP-1109`, `DALP-1074`, or `DALP-1110` (or `422` `CONTRACT_ERROR` with `Prefer: wait`). Successful changes record a fee payout to the old recipient.

**What to do.** Resume the asset or unfreeze and re-verify the old recipient before switching recipients, and reconcile the automatic payout.

### Pause and resume codes [#pause-and-resume-codes]

**What changed.** On the DALP 3.2 token contract, halting an already halted asset reverts with `DALP-1109` and resuming an active asset reverts with `DALP-9059` (the reverse of older contracts). `PATCH /api/v2/tokens/{assetId}/pause-state` also pre-checks indexed state and refuses redundant requests with `DALP-9488`. Contract codes surface when chain state leads the index, either in `contractError.id` or `422` `CONTRACT_ERROR` with `Prefer: wait`.

**Who is affected.** Clients branching on `DALP-1109` or `DALP-9059` after a halt or resume.

**How to detect it.** A redundant halt returns `DALP-1109` instead of `DALP-9059`, and a redundant resume returns the reverse.

**What to do.** Treat `DALP-9488`, `DALP-1109`, and `DALP-9059` uniformly as "the asset is already in the requested pause state".

### Prices with too many decimals [#prices-with-too-many-decimals]

**What changed.** Token price updates, price-feed submissions, and initial prices on token creation now refuse values with more decimal places than the feed stores, returning `400` `FEED_PRICE_NOT_REPRESENTABLE` (`DALP-12245`, non-retryable). 3.1 truncated extra digits toward zero.

**Who is affected.** Clients sending unrounded price strings.

**How to detect it.** Price writes return `400` `FEED_PRICE_NOT_REPRESENTABLE` naming the price and feed decimals.

**What to do.** Round or format prices to the feed's configured `decimals` before submitting.