Advanced Concepts
Failure Modes
Known runtime failure classes and current mitigation patterns.
Validation Failures
- malformed metadata keys
- missing referral identity on apply flows
- invalid tx hash and claim payloads
Mitigation: strict Zod validation at controller boundaries.
Queue-Level Failures
- invalid custom job IDs
- transient infra errors during async processing
Mitigation: sanitized IDs, retry with exponential backoff, DLQ terminal capture.
State Transition Races
Claim operation can race under concurrent requests.
Mitigation: guarded status transition to PROCESSING before payout, then finalize or rollback.
Cross-Service Contract Drift
API and worker both depend on shared service modules and Prisma model compatibility.
Mitigation: deploy migrations before runtime upgrades, keep API + worker on compatible commits.