Error handling

A failed API call needs two decisions: whether the request can succeed after a change, and whether an earlier write may still complete. Read the stable error identifier and retry flag, then check the transaction state before resubmitting an uncertain write. This page applies those rules to authentication, validation, custody, and on-chain failures.

Read the error contractCopy Anchor Link

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 catalog. See Read and handle DALP errors for the complete envelope and field table.

The SDK exposes API failures as DalpApiError. Network, configuration, and client-validation failures can occur without a DALP response or identifier. Check the SDK error kind before reading API fields.

Transport framing differs. A JSON-RPC error retains JSON-RPC framing; an SSE failure after stream start 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 retryCopy Anchor Link

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.

For a retryable failure, use a bounded backoff policy with jitter and honor 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 wallet-selection boundary.

Authentication, permissions, and validationCopy Anchor Link

An authentication rejection means the credential is absent, invalid, expired, or disabled. Confirm the X-Api-Key header and key record. An organization-scoped key also needs the organization 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 organization, 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 organization, and whether another operation changed the resource.

Pending work and idempotency conflictsCopy Anchor Link

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.

An idempotency conflict can mean the key expired, the wallet selection changed, or DALP could not safely attach the retry to an existing instruction. Read the exact code. Preserve the original key and instruction details while investigating. Changing only the recipient or amount does not reliably produce a conflict because the request body is not the transaction deduplication boundary.

For a FAILED or DEAD_LETTER instruction, read its failure detail before recovery. An authorized operator can requeue supported failed requests. Reusing the original key returns that instruction's current state; it does not by itself create a separate request.

Funding and custody failuresCopy Anchor Link

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.

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 failuresCopy Anchor Link

Onboarding deployment routes can reject with INDEXER_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. Without that preference, the durable workflow can wait for indexing instead.

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

Compliance failuresCopy Anchor Link

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 diagnostics require eligibility-read permission. A caller without it 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.

Criticality and escalationCopy Anchor Link

Every code in the Platform API error reference and the smart contract error code reference carries a Severity value. Severity is observability metadata that the error registry holds for the code. It is a default for your own alerting, not a service-level commitment, and the platform does not publish it as a log or metric level for every response. The error response does not include 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 table below only sets the default when the fix does not say.

Escalation order for a back office:

1. Match the data.id (or dalpCode) to its reference row, read its Severity, then follow the suggested fix. Use data.fix when the response carries it. 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 table sends the failure to SettleMint, open a support ticket with the record below. For a platform-wide symptom, check the status page first and include its incident reference.

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

Escalate with the instruction recordCopy Anchor Link

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 stepsCopy Anchor Link

• Read and handle DALP errors for the REST envelope.
• Idempotency and async settlement for retry identity and pending writes.
• Webhook outcomes for later retractions and recalls.