Appearance
Failure Types Reference
All failure states, error types, and recovery actions across Aset entities. Each failure type has corresponding mock data in apps/infra/db/seed.sql.
Overview
| Category | Count |
|---|---|
| Deposit States | 5 |
| Redemption Failures | 5 |
| Yield Failures | 4 |
| KYC/SBT States | 3 |
| Notification Failures | 6 |
Deposit Failures deposits.status + failure_type
Handle deposit processing, escrow management, and LP token minting with recovery workflows.
Status flow: PENDING → PROCESSING → COMPLETED or FAILED → REFUNDED
| Status | Failure Type | Error Example | Admin Display | Investor Display | Recovery |
|---|---|---|---|---|---|
| FAILED | LP_MINT_FAILED | ERC20: transfer amount exceeds balance | Red "LP Mint Failed" + error | "Your deposit could not be processed" | Admin retries or triggers refund |
| FAILED | RECEIPT_BURN_FAILED | ERC20: burn from zero address | Red "Receipt Burn Failed" | "Processing error — team investigating" | Admin checks receipt token state |
| FAILED | FM_NOTIFICATION_FAILED | SMTP delivery failed: mailbox unavailable | Yellow "FM Not Notified" + retry | Not shown (internal) | Admin retries FM notification |
| REFUNDED | — | — | Gray "Refunded" + timestamp | "Your deposit has been refunded" | No action needed |
| PROCESSING | — | — | Blue "Processing" + spinner | "Your deposit is being processed" | Auto-escalate if stuck > 1hr |
Additional fields: escrow_status: HELD | RELEASED | FAILED. Mock data: Deposit IDs 19–22 in seed.sql.
Redemption Failures redemption_requests.status + failure_type
Complex workflow with FM approval, lockup validation, and escrow funding checks.
Status flow: REQUESTED → FM_ACCEPTED (Fund Pool only) → PROCESSING → COMPLETED
| Status | Failure Type | Error Example | Admin Display | Investor Display | Recovery |
|---|---|---|---|---|---|
| FAILED | PAYOUT_TX_FAILED | Insufficient reserve balance in escrow | Red "Payout Failed" + escrow info | "Redemption could not be completed" | Admin tops up escrow, retries |
| FAILED | FM_NOTIFICATION_FAILED | SMTP connection refused on port 587 | Yellow "FM Not Notified" | Not shown to investor | Retry FM notification |
| FAILED | CONTRACT_EXECUTION_FAILED | execution reverted: InsufficientReserve | Red "Contract Error" + shortfall | "Processing error — contact support" | Admin addresses reserve shortfall |
| FAILED | FUND_TRANSFER_FAILED | ERC20: transfer exceeds allowance — approval expired | Red "Transfer Failed" + deadline | "Fund transfer pending" | FM renews wallet approval |
| REJECTED | LOCKUP_NOT_MET | Lockup period (180 days) has not elapsed | Gray "Rejected" + reason | "Cannot redeem: lockup active" | Wait until lockup expires |
Mock data: Redemption IDs 7–11 in seed.sql.
Yield Distribution Failures yield_distributions.status + failure_type
Automated yield accrual, batch claim processing, and transaction failure handling.
Status flow: PENDING → PROCESSING → DISTRIBUTED or FAILED
| Status | Failure Type | Error Example | Admin Display | Investor Display | Recovery |
|---|---|---|---|---|---|
| FAILED | TX_FAILED | Gas price exceeded maximum threshold | Red "TX Failed" + gas info | "Yield distribution delayed" | Admin retries with higher gas |
| FAILED | FM_NOTIFICATION_FAILED | SendGrid API error 429: rate limit exceeded | Yellow "FM Not Notified" | Not shown | Retry after rate limit resets |
| FAILED | DISTRIBUTION_TX_FAILED | ERC20 transfer failed — pool escrow insufficient | Red "Distribution Failed" + tx hash | "Yield distribution delayed" | Admin tops up escrow |
| FAILED | CLAIM_PROCESSING_FAILED | Batch claim tx gas estimation failed: out of gas for 4 recipients | Red "Claim Failed" + recipient count | "Yield claim pending" | Admin splits batch, retries |
Notes
Batch optimization for gas limits. Auto-retry up to 3x with exponential backoff. SendGrid rate limit: delayed retry (30min–2hr). Mock data: Yield IDs 8–11 in seed.sql.
KYC / SBT Failures users.kyc_status + sbt_status
Identity verification and Soul Bound Token minting with async mint operations.
KYC flow: PENDING → APPROVED / REJECTED
SBT flow: NOT_MINTED → MINTED / FAILED
| Entity | Status | Detail | Admin Display | Investor Display | Recovery |
|---|---|---|---|---|---|
| KYC | REJECTED | Failed identity verification | Red "KYC Rejected" + reason | "Verification unsuccessful — resubmit" | User resubmits KYC |
| KYC | PENDING | Awaiting review | Yellow "Pending Review" | "Under review" | Admin reviews |
| SBT | FAILED | TX timeout or chain error | Red "SBT Mint Failed" + tx hash | "Credential issuance failed" + retry | Admin triggers re-mint |
Notification Failures notification_logs.failure_type
Email delivery status tracking with recipient type handling and retry logic.
Status flow: SENDING → DELIVERED or FAILED
| Failure Type | Description | Error Example | Recipient | Auto-Retry | Recovery |
|---|---|---|---|---|---|
BOUNCED | Email permanently rejected | 550 5.1.1 The email account does not exist | FM, INVESTOR | No | Update email address |
SERVER_ERROR | Mail server error | SMTP connection refused (port 587) | FM, ADMIN | Yes (3x) | Check SMTP config |
TIMEOUT | Connection timeout | Connection timeout after 30s | FM | Yes (3x) | Check network/DNS |
INVALID_RECIPIENT | Email not found in system | Email address not found in system | INVESTOR | No | Verify user email |
SPAM_FILTERED | Content blocked by spam filter | 550 5.7.1 Message marked as spam | INVESTOR | No | Review email template |
RATE_LIMITED | API limit exceeded | SendGrid API 429: daily limit exceeded | INVESTOR | Yes (delayed) | Wait or upgrade plan |
Mock data: SPAM_FILTERED, RATE_LIMITED, SBT mint failure, LP mint failure, FM bounce in seed.sql.