Skip to main content

New refusals on platform operations in 3.2

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. For all other 3.2 changes, see Upgrade an integration to 3.2.

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

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.

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.

v1 writes under maker-checker

What changed. When an organisation enables 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

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

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. Update error handlers to match the 3.2 data.id values and codes.

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

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

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

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

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

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

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:

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.

Was this page helpful?