---
last_updated: 2026-08-08
tags: [fanavaran, errors, retry]
source: fanavaran-module-docs
---

# 09 — Error handling

## Principles

1. Fanavaran failures must **not** abort the local user claim flow on auto-submit.
2. Persist warning + history + `fanavaranSync.*.lastError`.
3. Allow manual retry via `/v2/fanavaran/.../submit`.
4. Audit only real Fanavaran HTTP (warm cache hits are silent).

---

## Common errors

| دلیل | پیام نمونه | مدیریت | Retry | Log | اطلاع‌رسانی |
|------|------------|--------|-------|-----|-------------|
| Wrong login / appToken | `نام کاربر یا رمز عبور صحیح نیست` | Fix credentials; ensure fresh GetAppToken before Login | After fix | Auth audit | Ops |
| Transient overload | `لطفا پس از چند لحظه مجدد تلاش فرمایید` | Tenant-wide backoff 5 min; do **not** immediately re-auth storm | Delayed (~5 min) | Auth + stage | Ops via audit |
| Missing PolicyId | No/expired policies messages | Block submit; preview may leave null | Manual after data fix | Stage fail history | Admin |
| Duplicate create | Local `claimId`/`claimNo` exists | Skip create; use follow-ups | N/A | skipReason | — |
| Invalid FileTypeId | `نوع فايل با منبع لوکاپ مطابقت ندارد` | Set `ClaimFileTypeId` from tenant `file-types` (Parsian **63**) | After config fix | Attachment stage | Ops |
| Expertise not ready | `Fanavaran expertise payload is not ready` + warnings | Wait for priced parts / factor | Auto when ready | — | Expert UI |
| Network / 5xx | Axios / gateway errors | Stage failed + schedule retry | Up to `maxRetries` (2) | Audit | Ops |
| Max retries exhausted | Logged warn | Manual submit only | Stop auto | Stage status | Ops |

---

## Retry mechanics

Implemented in `scheduleFanavaranRetry`:

| Rule | Behavior |
|------|----------|
| Delay (normal) | 5 minutes |
| Delay (transient try-later) | 10 minutes + `registerFailure` tenant backoff (5 min) |
| Max | Default 2 per stage (`fanavaranSync.*.maxRetries`) |
| Dedupe | In-process timer map + existing future `nextRetryAt` |
| Lock | `withFanavaranStageLock` prevents concurrent stage runs |

---

## History event types (examples)

| Event | Meaning |
|-------|---------|
| `FANAVARAN_EARLY_AUTO_SUBMIT_SUCCEEDED` | GEN.03 ok |
| `FANAVARAN_EARLY_AUTO_SUBMIT_FAILED` | GEN.03 fail |
| `FANAVARAN_DAMAGE_CASE_AUTO_SUBMIT_SUCCEEDED` / `_FAILED` | GEN.12 |
| `FANAVARAN_EXPERTISE_AUTO_SUBMIT_SUCCEEDED` / `_FAILED` | GEN.08 |
| Attachment success/fail | Via sync status + audit (and related history where pushed) |

---

## Audit log (`fanavaranAuditLogs`)

Per HTTP step:

- `requestUrl`, `requestMethod`, `httpStatus`, `durationMs`
- Headers/bodies (secrets masked, truncated)
- `errorMessage` / `errorDetails` on failure
- Look for `fromCache: true` meta when PolicyId/auth reused without live call

---

## SMS

The post-expertise owner SMS is disabled. A successful final Fanavaran response only persists the returned `expertiseId` and synchronization state; it does not dispatch a notification.