# New platform refusals in 3.2

Source: https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2-refusals-platform
Each DALP 3.2 platform 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 platform operation that refuses differently in DALP 3.2: list queries, the audit trail, maker-checker, asset classes, templates, documents, uploads, external tokens, compliance roles, and wallet factors. For token operation refusals, see [New token refusals in 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2-refusals). For all other 3.2 changes, see [Upgrade an integration to 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2).

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

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

### Flat collection keys are refused [#flat-collection-keys-are-refused]

**What changed.** v2 list routes using `page`, `sort`, and `filter` now refuse flat query keys (`limit`, `offset`, `sortBy`, `sortDirection`, `filters`) instead of converting them. Routes that declare their own flat `limit` (such as `GET /api/v2/transaction-requests`) keep accepting their declared keys.

Refusals return `400` `REQUEST_INVALID` (`DALP-14261`, non-retryable), naming the rejected key in `data.errors` (for example, `Collection query key "limit" is not supported: send sort, page[offset], page[limit], and filter[<field>]`).

**Who is affected.** Clients sending flat query keys to JSON:API collection lists.

**How to detect it.** List requests return `400` instead of `200`.

**What to do.** Send `page[limit]`, `page[offset]`, `sort`, and `filter[{field}]`. See [Pagination](https://docs.settlemint.com/docs/api-reference/guides/pagination).

### Audit trail busy [#audit-trail-busy]

**What changed.** Every v2 write records an audit entry before changing state. When concurrent writes in the same organisation hold the audit trail for more than 5 seconds, the request fails before changing anything with `503` `AUDIT_BUSY` (`DALP-9548`, `retryable: true`) and `Retry-After: 1`. v1 writes return `500` `INTERNAL_SERVER_ERROR` in the same situation.

**Who is affected.** Clients treating `503` on v2 writes as terminal or matching a fixed error list.

**How to detect it.** v2 writes return `503` with `data.id` `DALP-9548`.

**What to do.** Wait for `Retry-After` seconds and resend the request. The refused call wrote nothing, so retrying cannot duplicate the change. See [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling).

### v1 writes under maker-checker [#v1-writes-under-maker-checker]

**What changed.** When an organisation enables [maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) for a protection group, v2 writes in that group park for a second user's approval. Because v1 cannot hold requests, an authorised caller's v1 admin write is refused with `403` `FORBIDDEN` (non-retryable) whenever maker-checker covers its matching v2 route. Without that setting, v1 writes behave as in 3.1.

| v1 route group | `data.id` on `403` | Notes |
| --- | --- | --- |
| Token routes | `DALP-9485` | Existing route permission ID. |
| Platform routes | `DALP-12252` | Also newly added to `POST /api/v1/external-token/register`, `POST /api/v1/kyc-profile-versions/{versionId}/request-update`, `POST /api/v1/user/create`, and `POST /api/v1/user/admin/session/revoke`. |
| Identity, compliance, and user routes | `DALP-0003` | Existing route permission ID. |

**Who is affected.** v1 clients creating users, changing roles, freezing addresses, forcing transfers, or editing settings in organisations with maker-checker turned on.

**How to detect it.** A v1 write returns `403` with a message stating the organisation holds the change for a second user's approval.

**What to do.** Call the v2 route named in `data.fix`. It returns `202` and parks the change for approval.

### Shipped asset class slugs [#shipped-asset-class-slugs]

**What changed.** Creating or renaming a custom asset class to a shipped slug returns `409` `SETTINGS_TEMPLATE_NAME_ALREADY_EXISTS` (`DALP-0463`) with `The slug "{slug}" belongs to a system asset class. Choose a different name.`

| Shipped class | Allowed base types |
| --- | --- |
| `fixed-income` | `bond` |
| `equity` | `equity` |
| `funds` | `fund` |
| `cash` | `stablecoin`, `deposit` |
| `real-assets` | `real-estate`, `precious-metal` |
| `structured` | `bond`, `fund` |
| `derivatives` (new in 3.2) | `equity` |
| `yield-instruments` (new in 3.2) | `equity` |
| `digital-assets` | Every base type |

During upgrade, any custom class colliding with a shipped slug is reconciled. If all its templates match allowed base types, the shipped class adopts them and the custom class row is deleted. Otherwise the custom class keeps its ID and moves to `{oldSlug}-{first8CharsOfId}`. For `derivatives` and `yield-instruments`, orphaned templates split into the shipped class (`equity`) and `{oldSlug}-custom` (all other types).

**Who is affected.** Clients creating, renaming, or storing custom asset classes by slug.

**How to detect it.** Create or rename returns `409` `DALP-0463`, or post-upgrade lookups by slug return the shipped class and old class IDs no longer resolve.

**What to do.** Choose a non-reserved slug, key asset classes by ID, and refresh cached class lists after upgrading.

### Original asset families [#original-asset-families]

**What changed.** The seven original asset families (`bond`, `equity`, `fund`, `stablecoin`, `deposit`, `real-estate`, `precious-metal`) cannot be created or installed while legacy asset creation is off (the default). Introduced in 3.1.19, these refusals return updated non-retryable codes in 3.2 (existing tokens and factories are untouched):

| Operation | 3.1 response | 3.2 response |
| --- | --- | --- |
| v2 token creation | `400` `TOKEN_CREATE_TYPE_DEPRECATED` (`DALP-9103`) | `422` `TOKEN_CREATE_ASSET_FAMILY_DEPRECATED` (`DALP-12075`) |
| v2 factory installation | `400` `TOKEN_FACTORY_TYPE_DEPRECATED` (`DALP-9104`) | `422` `PLATFORM_FACTORY_TYPE_UNUSABLE` (`DALP-14339`) |
| v1 token creation | `400` | `422` `INPUT_VALIDATION_FAILED` (`DALP-9243`) |

**Who is affected.** Clients creating tokens from the seven original families or branching on 3.1 codes.

**How to detect it.** `data.features.legacyAssetCreation` on `GET /api/v2/settings/public-config` reads `false`.

**What to do.** Issue from a published instrument template, or ask your operator to enable legacy asset creation per [Decide on legacy asset creation](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-legacy-asset-creation). Update error handlers to match the 3.2 `data.id` values and codes.

### Template publication [#template-publication]

**What changed.** Organisations can issue only from published templates and structures. Custom templates start published. Among shipped templates, only Equity, Bond, and Stablecoin start published, while all others start unpublished.

| Operation | 3.2 refusal (non-retryable) |
| --- | --- |
| v2 token create (unpublished template) | `409` `TOKEN_CREATE_TEMPLATE_UNPUBLISHED` (`DALP-14019`) |
| v2 issuance run (unpublished member template) | `409` `TOKEN_ISSUANCE_RUN_TEMPLATE_UNPUBLISHED` (`DALP-14020`) |
| v2 issuance run (unpublished structure) | `409` `TOKEN_ISSUANCE_RUN_STRUCTURE_UNPUBLISHED` (`DALP-14024`) |
| v1 token create (unpublished template) | `422` `INPUT_VALIDATION_FAILED` (`DALP-0316`) |

**Who is affected.** Clients issuing tokens or running issuances from templates other than Equity, Bond, or Stablecoin.

**How to detect it.** `isPublished` is `false` on the template, or issuance returns one of the codes above.

**What to do.** Publish the template via `PUT /api/v2/settings/asset-type-templates/{assetTypeTemplateId}/publication` or in the Console, then retry.

### Asset documents [#asset-documents]

**What changed.** Three document and template operations return tighter codes:

- Confirming an asset document with a `replaceGroupId` belonging to a different `documentType` returns `404` `DALP-0322` instead of appending a version of the new type.
- Deleting a document without the governance role returns `403` `DALP-9485` regardless of whether the document exists (3.1 returned `404` if missing).
- Deleting an instrument template that already issued tokens returns `409` `DALP-181131` instead of `500`.

**Who is affected.** Clients replacing or deleting asset documents or deleting instrument templates.

**How to detect it.** Responses carry `DALP-0322`, `DALP-9485`, or `DALP-181131` in `data.id`.

**What to do.** Keep replacements within the same `documentType`, treat `403` on delete as a missing role, and do not delete templates with issued tokens.

### v1 KYC document uploads and downloads [#v1-kyc-document-uploads-and-downloads]

**What changed.** v1 KYC document confirms now validate declared size, the 25 MiB cap, and actual file bytes, then store the file encrypted (deleting invalid uploads on refusal). Unconfirmed presigned uploads are deleted 30 minutes after link creation.

Both v1 and v2 KYC download calls now return a relative `/api/v2/...` path requiring your session or API key instead of an unauthenticated storage URL. Existing unencrypted v1 uploads are encrypted in the background.

**Who is affected.** Clients using v1 presigned KYC uploads or fetching KYC `downloadUrl` without credentials.

**How to detect it.** `downloadUrl` starts with `/api/v2/` instead of `https://`, and mismatched file types or sizes fail confirm.

**What to do.** Resolve relative `downloadUrl` values against `$DALP_API_URL`, attach your session or `X-Api-Key`, declare exact size and MIME type on confirm, and prefer the v2 upload route.

### Presigned uploads write once [#presigned-uploads-write-once]

**What changed.** Presigned upload responses now include a create-only header (`If-None-Match: *`, or `x-goog-if-generation-match: 0` on Google Cloud Storage) so object storage accepts only the first upload to a link. 3.1 allowed overwriting until link expiry.

**Who is affected.** Clients hard-coding upload headers instead of forwarding the returned `headers`, or reusing an upload URL.

**How to detect it.** Direct uploads return `403` or `412` when a header is omitted, and `409` or `412` on a second upload to the same URL.

**What to do.** Send every returned header verbatim and request a new upload URL for every file.

### External token registration [#external-token-registration]

**What changed.** `POST /api/v2/external-tokens` and `POST /api/v1/external-token/register` now validate role, ownership, duplicate registration, and `tokenType` (`bond`, `equity`, `fund`, `stablecoin`, `deposit`, `cryptocurrency`, `other`) before checking `walletVerification` or queueing a transaction. All refusals are non-retryable.

| Condition | v2 response | v1 response |
| --- | --- | --- |
| Missing `tokenManager` (Asset manager) role | `403` `EXTERNAL_TOKEN_MANAGER_REQUIRED` (`DALP-0751`, was `DALP-0006`) | `403` `FORBIDDEN` (`DALP-12252`) |
| Platform-managed token or system contract | `409` `EXTERNAL_TOKEN_PLATFORM_MANAGED` (`DALP-210801`) | `422` `INPUT_VALIDATION_FAILED` (`DALP-0736`) |
| Already registered manually (not dismissed) | `409` `EXTERNAL_TOKEN_ALREADY_REGISTERED` (`DALP-0730`) | `422` `INPUT_VALIDATION_FAILED` (`DALP-0736`) |
| Already held as auto-detected or dismissed | Re-registers cleanly | `422` `INPUT_VALIDATION_FAILED` (`DALP-0736`, use v2 instead) |
| Invalid `tokenType` | `400` `REQUEST_INVALID` (names `tokenType`) | `400` `BAD_REQUEST` (`DALP-0001`) |

**Who is affected.** Clients registering external tokens or matching `DALP-0006` for missing roles.

**How to detect it.** v2 returns `409`, `403` `DALP-0751`, or `400` instead of `202` or `DALP-0006`. v1 returns `422` `DALP-0736` or `403` `DALP-12252`.

**What to do.** Call with a `tokenManager` account, use one of the seven `tokenType` values, register only external contracts, and treat `DALP-0730` by reading `GET /api/v2/external-tokens`. Existing 3.1 registrations keep their stored type.

### Compliance writes without the needed role [#compliance-writes-without-the-needed-role]

**What changed.** Organisation members calling a compliance write without a required role now receive `403` `compliance.role.REQUIRED` (`DALP-12422`, non-retryable) with `data.requiredRoles` instead of `404` `compliance.scope.DENIED` (`DALP-12283`).

This applies to `/api/v2/system/compliance-modules`, `/api/v2/tokens/{assetId}/compliance-modules`, token compliance expression, policy, and holder-lock writes, `/api/v2/compliance/providers`, KYC review writes on `/api/v2/kyc-profile-versions/{versionId}` (`decisions`, `approvals`, `update-requests`), and `PATCH` or `decisions` on `/api/v2/organisation-kyc-profile` and `/api/v2/users/{userId}/profile`. KYC and profile writes check the role before looking up the target. Out-of-organisation callers, unknown targets on token routes, all reads, and v1 routes still return `404` `DALP-12283`.

**Who is affected.** Clients treating `DALP-12283` on compliance writes as a missing role.

**How to detect it.** Compliance writes return `403` `DALP-12422` instead of `404` `DALP-12283`.

**What to do.** Grant one of the roles in `data.requiredRoles` (or act as an account holding one) on `DALP-12422`, and treat `DALP-12283` as an unknown or out-of-organisation target.

### Wallet factor changes need a factor and a challenge [#wallet-factor-changes-need-a-factor-and-a-challenge]

**What changed.** The six wallet factor routes under `POST /api/auth/wallet/` (`pincode/enable`, `pincode/update`, `pincode/disable`, `two-factor/enable`, `two-factor/disable`, and `secret-codes/generate`) no longer accept the account password once an account holds any wallet factor (PIN, wallet authenticator/transaction code, confirmed recovery codes, or identity-provider authenticator).

Instead, each request must prove an existing factor in `walletVerification` and include a single-use `X-Step-Up-Challenge` header. Accounts with no enrolled factor need neither. Sending only a password returns `400` (such as `WALLET_PINCODE_PASSWORD_REQUIRED`). Missing or invalid challenges return `403` `WALLET_STEP_UP_CHALLENGE_REFUSED` without checking the factor or counting toward [wallet verification lockout](https://docs.settlemint.com/docs/console/my-account/security#lockout-after-wrong-codes):

| `fault` | Cause |
| --- | --- |
| `missing` | Request has no `X-Step-Up-Challenge` header. |
| `unknown` | Challenge was not issued to this user, was already spent, or was cleared after expiry. |
| `expired` | More than 5 minutes elapsed since issue. |
| `mismatch` | Organisation, route, target, or `payloadDigest` differs from the issued challenge. |

**Who is affected.** Clients modifying wallet factors from a signed-in session. Users of `createDalpAuthClient` from the 3.2 SDK receive challenges automatically but must still send a current factor instead of a password.

**How to detect it.** Password-only calls return `400`, and calls with `walletVerification` but no challenge return `403` with `fault: "missing"`.

**What to do.** Use `createDalpAuthClient` or `withStepUpChallenge` from `@settlemint/dalp-sdk/auth`, or implement the 3-step challenge flow directly:

1. Compute `payloadDigest`: lowercase hex SHA-256 of `{"issuer":"{issuer}"}` (no spaces) for `POST /api/auth/wallet/two-factor/enable` when `issuer` is set, or SHA-256 of `{}` (`44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a`) for every other factor change.
2. Call `POST /api/v2/step-up-challenges` as the same signed-in user and organisation with `operation` (such as `"POST /api/auth/wallet/pincode/update"`), `target: null`, and `payloadDigest`.
3. Within 5 minutes, send the factor change with `data.challengeId` in `X-Step-Up-Challenge`.

Every attempt reaching the challenge check consumes its challenge even when the factor fails, so request a fresh challenge per attempt. If a response is lost, read the account's enrolled factors before retrying so an already-changed PIN or recovery code does not trigger lockout.