forked from Yara724/api
73 lines
3.2 KiB
Markdown
73 lines
3.2 KiB
Markdown
---
|
|
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
|
|
|
|
After successful expertise (last Fanavaran stage), owner SMS may be sent once (`fanavaranSync.expertise.smsNotifiedAt`). Failure to SMS should not roll back Fanavaran expertise submit; treat as separate notification concern. Claims already notified at base claim (`fanavaranSync.baseClaim.smsNotifiedAt`) are not re-notified.
|