Skip to main content

Error handling

Handle DALP API failures with stable error identifiers, retry decisions, and support-ready diagnostics.

A failed API call needs three decisions: whether the request can succeed after a change, whether an earlier write may still complete, and who on your side handles it. Read the stable error identifier, such as DALP-12074, and the retryable flag, then check the transaction state before you resubmit an uncertain write. This page applies those rules to authentication, validation, funding, custody, indexing, deployment and compliance failures, and sets the escalation order for a back office.

Read the error contract

Versioned REST routes return code, status, message, and a data object. The data carries the stable DALP identifier, reason, recovery step, retry flag, and category when the failure maps to the catalogue. See Read and handle DALP errors for the complete envelope and field table.

The SDK raises an API failure as DalpApiError, with the DALP identifier in id and the machine name in code. When code starts with sdk. or is DALP_SDK_ERROR, the SDK raised the error itself, after a network, configuration or response-format failure, or an answer the route does not publish. Read the API fields only on other codes. waitForTransaction raises its own DalpTransactionWaitError.

Transport framing differs. A JSON-RPC error keeps JSON-RPC framing. An SSE failure after the stream starts arrives as an event. Read the documented schema for that transport instead of assuming every failure is an HTTP JSON body.

Use these fields in order:

  1. Identify the failure by its stable data.id or the SDK's id.
  2. Read retryable and the recovery instructions before retrying.
  3. Show message, why, and fix to the person who can resolve the condition.
  4. Retain the request identifier when supplied, plus the affected resource and transaction-request identifier.

Do not parse human-readable messages for control flow. Look up the identifier in the DALP error index.

Decide whether to retry

Three checks decide whether to retry a failed call.After a failed call, first ask whether the write outcome is uncertain. If it is, read the existing instruction state through its status URL before going on. Then check the retryable flag. If it is false, follow the recovery step and show message, why and fix to the person who can act. If it is true, check whether the required condition is resolved. If not, fund the wallet, get the approval or honour Retry-After first. Once it is resolved, retry with bounded backoff and keep the Idempotency-Key of the same instruction.Three checks decide whether to retry a failed call.After a failed call, first ask whether the write outcome is uncertain. If it is, read the existing instruction state through its status URL before going on. Then check the retryable flag. If it is false, follow the recovery step and show message, why and fix to the person who can act. If it is true, check whether the required condition is resolved. If not, fund the wallet, get the approval or honour Retry-After first. Once it is resolved, retry with bounded backoff and keep the Idempotency-Key of the same instruction.

After a failed call, check the write outcome, then retryable, then the required condition, and retry only with bounded backoff.

When the outcome of a write is uncertain, such as after a timeout, read the existing instruction state through its status URL before you go on. When retryable is false, follow the recovery step and show message, why and fix to the person who can act on them. When it is true, first resolve the required condition: fund the wallet, get the approval or honour Retry-After. Then retry with bounded backoff and keep the Idempotency-Key of the same instruction.

HTTP status alone does not decide retryability. Some 4xx errors become recoverable after funding or approval. An unknown 500 does not prove a retry is safe. Follow the code's retry flag and recovery step.

On an error the SDK raised itself, retryable is the SDK's own estimate: it is true after a network failure, an unreadable response, a failed stream or a 5xx without a DALP body. Read the state of a write before you retry it after one of these.

For a retryable failure, use a bounded backoff policy with jitter and honour Retry-After when supplied. For example, your integration can wait 1, 2, and 4 seconds plus jitter, then stop and report the unresolved failure. This is an example client policy, not a platform guarantee.

A request timeout does not cancel a transaction. Keep its original Idempotency-Key, follow its returned status URL, and record any transaction hashes. Create a new instruction with a new key only after confirming the earlier outcome and deciding a separate write is required. Idempotency and async settlement defines the 24-hour window and the wallet-selection rule.

Authentication, permissions, and validation

An authentication rejection means the credential is absent, invalid, expired or disabled, or the session lacks a required step such as two-factor authentication or a step-up challenge. Read the code. Confirm the X-Api-Key header and key record. An organisation-scoped key also needs the organisation context stored with it. See Authentication and API keys.

A permission rejection means the authenticated caller lacks access to the operation or resource. Check the current organisation, participant context, and required roles. Repeating the request with the same permissions does not resolve it.

For a validation rejection, inspect the route's documented error data and correct the named fields. A missing resource or state conflict requires a current read: verify the identifier, selected organisation, and whether another operation changed the resource.

Pending work and idempotency conflicts

202 Accepted is a normal pending result for a transaction-writing route. Poll the returned status URL or follow its documented stream. An instruction waiting for custody approval is still pending. Submitting another instruction can duplicate the intended action. A change held for a second user's approval also answers 202, and the SDK raises it as sdk.transport.APPROVAL_HELD with retryable: false. Do not repeat that request: read the approval at the status URL it names.

An idempotency conflict means the key now names a different write. The target contract, call data or value changed, which covers a changed recipient or amount. Or the wallet selection changed, or the key's 24-hour window closed. Read the exact code. Keep the original key and instruction details while you investigate.

For a FAILED or DEAD_LETTER instruction, read the transaction request before any recovery. A DEAD_LETTER call that was broadcast or filed with a custody provider can still land on the chain. Reusing the original key does not requeue a failed instruction. When it failed before anything was signed, a matching resubmission under the same key starts a new request, and the failed one keeps its own id. Otherwise the replay returns the recorded failure, such as TRANSACTION_QUEUE_DUPLICATE_SETTLED or TRANSACTION_QUEUE_DEAD_LETTER. Read the transaction request, and send a new key only when it shows FAILED or CANCELLED, or DEAD_LETTER with mayStillLand: false.

An authorised operator can force a retry of a failed request. When the chain does not show the original call, the operator states that the call was stopped, for a custody call after checking with the provider. The platform does not verify that statement, and it records the operator and the reason with the retry.

Funding and custody failures

For GAS_REQUIRED, inspect the network and wallet named by data.chainId and data.address. Amounts such as shortfallWei and recommendedTotalWei are integer strings in the network's gas-token base units. Verify the destination and current fee conditions before funding it, then inspect the original instruction before resubmitting. Gas sponsorship explains which wallet pays on each network and how a funding pause resolves.

A token role change, or a token or token-feature write that sends its transaction directly, answers 400 with TRANSACTION_QUEUE_FUNDING_REQUIRED when the call waits for the result and the platform refused it for gas. data.refusal is FundingRequired, and data.transactionId names the transaction request when the platform recorded one. That request keeps the GAS_REQUIRED detail, so read it to find the wallet and the shortfall before you fund it.

A token role change from an EOA executor wallet answers this way whether the first call or a later one was refused, as long as the platform undid every earlier call. When it could not undo one of them, it answers 422 with TOKEN_WORKFLOW_FAILED and no data.refusal, and you should read the held roles before another write.

A coordinated distribution's preview, abort and leg release, and the confirm of a corporate action that issues or burns units for each holder when its first batch stops before anything is sent, answer the same way when a step stops for gas. The corporate action keeps its progress, so fund the wallet and send the same step again. Send that confirm with a new Idempotency-Key, because the refused batch stays recorded under the first key.

A token creation and a token price update answer the same way when the call waits for the result. A price write that the queue accepted, and whose funding window then closed while the call waited, answers 503 with TOKEN_WRITE_PERSISTENCE_FAILED instead. That holds for a price update and for the initial price of a token creation. A retry that sends the same Idempotency-Key answers TRANSACTION_QUEUE_DUPLICATE_SETTLED, so fund the paying account and send the call again under a new key. A token creation refused after its token was deployed answers 500 with TOKEN_CREATE_WORKFLOW_FAILED. That answer says the token can exist, so check for it before you create it again. Its data.step names the failed step and data.reason the kind of failure. When the initial price could not be published (data.step is TOKEN_CREATE_STEP_PRICE_FEED_PUBLISH), data.reason is price-feed-not-authorized when the token's price feed does not trust the organisation's feed signer, price-feed-conflict when a feed already holds the token's price topic or a newer answer, and price-feed-unavailable when the feed, the feed directory or the feeds add-on could not serve the write. Any step whose payload the organisation's custody signer could not sign answers signing-failed.

A Luna HSM signing request fails when the required partition approval does not arrive inside the signing window. Ask the HSM operator to activate the partition before retrying. When the observed partition state and the signing result disagree, the instruction also fails. Inspect the HSM state and retain the request identifier for support.

Other providers have their own policy and availability failures. The Platform API error reference gives per-code recovery steps.

Indexing and deployment failures

Onboarding deployment routes can reject with DALP-12331, machine name platform.http.REINDEXING, when a request opts into Prefer: dalp-fail-on-indexer-reindexing. The response includes Retry-After and data.retryAfterSeconds. Wait for the indicated interval before retrying, with a bounded client deadline.

A write can answer 504 with INDEXER_BARRIER_TIMEOUT, id DALP-12074. The transaction succeeded on chain, but its block was not indexed before the request deadline. retryable is false, because the write has already happened and must not be sent again. Read the transaction request with data.transactionId, then repeat the read that needs the indexed result. If the index stays behind, ask the platform operator to inspect indexing for data.chainId at or before data.blockNumber.

A deployment can fail after acceptance. Read the structured failed-step data in the status response or the deployment stream. Known contract and workflow failures can carry dalpCode, retryable, selector, solidityError and a correlation identifier. Preserve those fields, because a generic display message is not enough to diagnose which step failed.

Compliance failures

A failed mint or transfer can carry data.args.reason with one of these values:

Reason
Meaning
Recovery
identity-not-registered
The wallet is absent from the token's identity registry.
Register the correct identity before retrying.
identity-not-verified
Required claims are missing, revoked, or expired.
Resolve the claim requirements with a trusted issuer.
module-blocked
A compliance module refused the operation.
Review the active policy and the reported module detail.
stale-price
A required price is older than the allowed window.
Restore a current observation and repeat the check.
classification-unavailable
DALP could not read the token's trusted issuer registries to classify the refusal.
Branch on the error id and read the general refusal.

Classification is best effort. Branch first on the stable error identifier, then use args when present. An absent classification is a supported response, not a decoding failure.

Detailed transfer and mint diagnostics need the executing wallet to hold the System manager, Identity manager or Verification issuer role, and mint diagnostics also accept the Supply management role. A caller without one receives the general refusal. Forced-transfer classification is narrower and can report an unregistered identity while other failures retain the general message. These restrictions prevent errors from disclosing another participant's compliance state.

Two kinds of write do not meet every compliance module. A custodian's forced transfer and a lost-wallet recovery skip the compliance modules and run while the token is paused. A transfer to an address on the compliance bypass list skips the rules that judge the recipient, including transfer approval. DALP manages that list: the token and add-on factories add the contracts they deploy, and no Console screen or Platform API route edits it directly. Who manages the compliance bypass list says who can still change it. Roles and segregation of duties lists who holds each power.

Criticality and escalation

Every code in the Platform API error reference and the Contract error reference carries a Severity value. Severity is metadata that the error registry holds for the code. It is a default for your own alerting, not a service-level commitment. The platform logs each error response at that level, but the response does not carry it, so look it up by the stable data.id. When an asynchronous deployment or workflow failure has no data.id, look up its dalpCode instead and read the matching reference row. The row's suggested fix is the authority for what to do. The severity table sets the default only when the fix does not say.

Severity
What it means
Who handles it
Escalate to support when
info
An expected rejection a caller triggers in normal use, such as a validation failure, a missing API permission or a route-level compliance check.
The calling application or the operator who submitted the request. Count it. Do not page anyone.
Never on a single occurrence. Open a ticket only when the rate rises with no change on your side.
warning
A recoverable or state-based refusal: a transient condition (confirmation timeout, request deadline, incomplete indexed data) or a state that blocks the action (paused contract or token, already approved or claimed).
Your integration. Retry only when the retry flag is true. Otherwise wait for the state to change.
A retryable code persists after bounded retries, or the affected instruction never reaches a terminal state.
error
A failure that stops the operation until something changes: a dependency fault, an on-chain revert (including a compliance or role revert) or an operational fault.
A person on your side who can act on the suggested fix.
The suggested fix tells you to contact support, or the failure persists after you apply it. A dependency, operational or unknown failure that persists goes to support.
fatal
Reserved for a failure that leaves the platform unable to serve requests. No catalogued code uses it.
Treat as an incident: page your on-call owner.
Immediately.

Escalation order for a back office:

  1. Match the data.id (or dalpCode) to its reference row, read its Severity, then follow the step in data.fix. Read the retry flag from data.retryable. A failed deployment or workflow step carries retryable directly on its error object instead.
  2. For a warning, retry with the bounded policy only when the retry flag is true, and check the instruction state before any resubmission.
  3. For an error, change the request, credentials, permissions, or asset state the suggested fix names. Escalate when the fix says to contact support or does not resolve the failure.
  4. When the severity table sends the failure to support, open a ticket with the instruction record. On an instance your organisation operates, your platform operator handles dependency and operational failures first.

Do not resubmit an uncertain write while you wait for support. Read the original instruction's state instead.

Escalate with the instruction record

Include the public error code, request identifier when supplied, route, timestamp in UTC, affected resource, idempotency key, and transaction status URL. Add the custody approval reference when relevant. Keep credentials, signing secrets, raw provider responses, and identity documents out of the support note.

Next steps

Was this page helpful?