Errors overview

This section catalogs the errors integrations encounter when calling DALP. Two reference pages list every code; a handling guide explains retry, idempotency, and escalation; this overview is the entry that routes you to the right place by the kind of error you have.

When to read what

The reference pages are auto-generated from the source code. They are large because they cover every code DALP can return; use this overview to jump to the relevant section instead of scrolling.

Smart contract error code domains

The smart contract error code reference groups codes by the operation that triggered them. Use the anchor link to jump to the relevant domain:

• Compliance and token operations — identity verification, country restrictions, allow-list and block-list rejections, transfer approvals, supply-cap and collateral checks, and other compliance-module rejects.
• Settlement and XvP — XvP settlement state transitions, hashlock or window failures, approval errors, and cancellation rejections.
• Airdrop and distribution — distribution-state rejections from the airdrop addon and its claim-tracker variants.
• System and infrastructure — system contract, directory, registry, factory, and access-manager rejects.
• Internal (OpenZeppelin and low-level) — OpenZeppelin selector-revert payloads (e.g., Ownable, AccessControl, Pausable) and other low-level reverts surfaced when no higher-level cause is available.

The reference page ends with a summary table of counts per domain.

DAPI error domains

The dapi error reference lists every dapi-emitted error code. Use the anchor links to jump to the relevant section in the long reference. The dapi codes follow a single naming scheme (DALP-NNNN) and are grouped by the HTTP status they map to:

• Authentication and authorisation rejections (401, 403).
• Request validation rejections (400, 422).
• Rate-limit and quota rejections (429).
• Upstream and external integration failures (502, 503, 504).
• System and platform rejections (500).

Every code carries a fixed shape: code identifier, category, HTTP status, retryable flag, message, why, and fix guidance. Integrations should branch on the dapiError.id field, not on the message text.

Handling guidance

The error-handling guide covers the cross-cutting concerns:

• Retry policy: which errors are retryable, which carry an idempotency contract, and how to back off.
• Idempotency: how to use idempotency keys with mutation endpoints to make retries safe.
• Status polling: how to follow asynchronous blockchain mutations through their lifecycle.
• Error envelopes: the shape of the error response across REST, RPC, and bundler routes.
• Support evidence: which request and response fields to include when escalating an unresolved error.

Read the handling guide before integrating against the references. The references describe what each code means; the handling guide describes what your integration does about it.

Generation contract

The two reference pages are generated by the platform's contract-error registry codegen:

• packages/dalp/api-contract/tools/generate-error-catalog.ts writes error-code-reference.mdx from the smart-contract error catalog.
• packages/dalp/api-contract/tools/codegen-paths.ts configures where both generated pages land.

Changes to the platform's error surface land first as source-code updates to the contract or dapi error definitions; the codegen tool regenerates the reference pages on the next build. The overview, anchor links, and handling guide on this page do not regenerate — keep them aligned with the reference structure when major domain shifts ship.

Read next

• dapi error reference
• Smart contract error code reference
• Error handling
• Transaction tracking for status polling against async blockchain mutations.