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/) 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-. 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.
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_ (DALP-0463) with The slug "{slug}" belongs to a system asset class. Choose a different name.
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 {old. 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):
Who is affected. Clients creating tokens from the seven original families or branching on 3.1 codes.
How to detect it. data. on GET /api/ 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.
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/ or in the Console, then retry.
Asset documents
What changed. Three document and template operations return tighter codes:
- Confirming an asset document with a
replaceGroupIdbelonging to a differentdocumentTypereturns404DALP-0322instead of appending a version of the new type. - Deleting a document without the governance role returns
403DALP-9485regardless of whether the document exists (3.1 returned404if missing). - Deleting an instrument template that already issued tokens returns
409DALP-181131instead of500.
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-, or x- 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/ and POST /api/ 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.
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/. 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 /, /, token compliance expression, policy, and holder-lock writes, /, KYC review writes on / (decisions, approvals, update-requests), and PATCH or decisions on / and /. 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/ (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_). Missing or invalid challenges return 403 WALLET_ without checking the factor or counting toward wallet verification lockout:
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/, or implement the 3-step challenge flow directly:
- Compute
payloadDigest: lowercase hex SHA-256 of{"issuer":"{issuer}"}(no spaces) forPOST /api/whenauth/ wallet/ two- factor/ enable issueris set, or SHA-256 of{}(44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a) for every other factor change. - Call
POST /api/as the same signed-in user and organisation withv2/ step- up- challenges operation(such as"POST /),api/ auth/ wallet/ pincode/ update" target: null, andpayloadDigest. - Within 5 minutes, send the factor change with
data.challengeIdinX-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.