Errors, retries, and troubleshooting
First rule
After a timeout or transport error, do not assume the command failed. Query the authoritative Canton, account, transfer-offer, or Bitcoin state before retrying.
Error classes
Configuration
Wrong endpoint, party, package, network
Stop and correct configuration
Authentication
Expired token, wrong audience, missing rights
Refresh or correct access, then re-query state
Validation
Bad amount, destination, offer, or contract
Do not retry unchanged
Conflict
Archived contract or concurrent action
Refresh active state and rebuild
Transport
Timeout, disconnect, unavailable service
Determine commitment before retrying
External lifecycle
Bitcoin confirmation or attestation delay
Monitor the existing workflow
Idempotency pattern
Use one business reference and command identifier for one intent where supported. Persist it before submission. On uncertainty, search by that reference and resulting contract or update identifiers.
Retry policy
Retry only operations documented as safe. Use bounded exponential backoff with jitter for read-only transport failures. Do not automatically retry mint, redemption, transfer acceptance, cancellation, or account creation without checking state.
Support evidence
Collect the environment, UTC time, release set, party, sanitized request reference, Canton update or contract identifiers, Bitcoin transaction identifier where relevant, error code, and logs with secrets removed.
Related pages
Next step
👉 Still blocked? Support and developer resources.
Last updated