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:
- Identify the failure by its stable
data.idor the SDK'sid. - Read
retryableand the recovery instructions before retrying. - Show
message,why, andfixto the person who can resolve the condition. - 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
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. 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_ or TRANSACTION_. Read the transaction request, and send a new key only when it shows FAILED or CANCELLED, or DEAD_LETTER with may.
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_ 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_ 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_, 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_. 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_), data.reason is price- 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-. 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:
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.
Escalation order for a back office:
- Match the
data.id(ordalpCode) to its reference row, read its Severity, then follow the step indata.fix. Read the retry flag fromdata.retryable. A failed deployment or workflow step carriesretryabledirectly on its error object instead. - For a
warning, retry with the bounded policy only when the retry flag is true, and check the instruction state before any resubmission. - 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. - 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
dependencyandoperationalfailures 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
- Platform API error reference and Contract error reference for every error id.
- Read and handle DALP errors for the REST envelope.
- Idempotency and async settlement for retry identity and pending writes.
- Webhook outcomes for event finality and later retractions.