All Docs
FeaturesDepositClearUpdated March 14, 2026

AI Assessment Failure Retry & Degraded Fallback

AI Assessment Failure Retry & Degraded Fallback

Available from v0.1.329

The AI deduction assessment pipeline includes a built-in resilience workflow that handles transient AI failures gracefully. Rather than leaving an assessment silently in a failed state, the system automatically attempts recovery and — if recovery fails — guides the user to a manual alternative.

How It Works

1. Failure Detection

The workflow is event-driven, triggered by the ai/assessment.failed event. This event fires when an aiDeductionAssessments row reaches status='failed' after all Inngest retries have been exhausted at the infrastructure level.

2. Staleness Check

Before taking any action, the system checks the failedAt timestamp on the assessment row:

ConditionBehaviour
failedAt < 24 hours agoProceed with retry logic
failedAt ≥ 24 hours agoNo action taken; assessment stays failed

This prevents redundant retries for old or abandoned assessment jobs.

3. Automatic Retry

If the failure is recent, the system re-queues a single retry attempt for the assessment. This covers the most common case: a brief, transient AI service outage or timeout.

4. Degraded Fallback (Second Failure)

If the retry attempt also fails, the workflow enters a degraded fallback mode:

  1. In-app notification — A warning is inserted into the notifications table for the user who requested the assessment. The message clearly states that AI assessment is temporarily unavailable.
  2. Manual guidance link — The notification includes a direct link to the manual deduction guidance page, so the user can proceed without the AI.
  3. Error message update — The aiDeductionAssessments row is updated with a human-readable errorMessage field, making the failure reason visible to both the user and support staff.

Affected Entities

EntityChange
aiDeductionAssessmentsstatus set to 'failed'; errorMessage populated on second failure
notificationsIn-app warning record inserted for the requesting user
usageEventsUsage event recorded for audit/tracking
usersNotification targeted to the requesting user

User Experience

When a user's AI assessment cannot be completed, they will:

  • See an in-app warning banner or notification explaining the situation in plain language.
  • Be offered a link to manual deduction guidance as an immediate alternative.
  • Never be left waiting indefinitely with no feedback.

This ensures compliance with the platform's commitment to fair, transparent outcomes — even when AI services are degraded.

Trigger Summary

Event:   ai/assessment.failed
Type:    Escalation
Retries: 1 automatic retry (if failedAt < 24h)
Fallback: In-app notification + manual guidance link + errorMessage update

Related