generated from john/python-template
43 lines
2.7 KiB
Markdown
43 lines
2.7 KiB
Markdown
# Ver1 Step 2 Error-Path Inventory (Carry-Forward)
|
|
|
|
## Purpose
|
|
|
|
Provide a compact inventory of major failure paths with taxonomy mapping and retry behavior, aligned with:
|
|
- `docs/error_handling.md`
|
|
- `docs/ver1/ver1-step2-results.md`
|
|
- `docs/ver1/ver1-step1-2-carry-forward-checklist.md` (CF-B1)
|
|
|
|
This is a lightweight operational artifact for Step 6/7 follow-through.
|
|
|
|
---
|
|
|
|
## Inventory Table
|
|
|
|
| Path ID | Boundary/Operation | Typical Failure Source | Category | Retriable | Surface Behavior | Current Coverage | Notes |
|
|
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
| EP-API-001 | API upload request validation | invalid payload / empty file metadata | `validation_error` | no | structured API error envelope (400) | partial | confirm all upload variants |
|
|
| EP-API-002 | API resource lookup | missing job/document | `not_found_error` | no | structured API error envelope (404) | partial | verify consistency for all lookup routes |
|
|
| EP-SVC-001 | Service provider-call mapping | provider SDK/HTTP failure | `external_provider_error` | sometimes | normalized AppError and safe message | partial | ensure consistent mapping in service boundary tests |
|
|
| EP-WKR-001 | Worker provider timeout | timeout/unavailable upstream | `external_provider_error` or `infrastructure_transient_error` | yes | retry or terminal failed with persisted reason | partial | validate category mapping remains deterministic |
|
|
| EP-WKR-002 | Worker non-retriable domain/input failure | deterministic invalid input/state | `user_input_error` or `conflict_error` | no | immediate terminal failed with persisted reason | partial | ensure no retry on non-retriable categories |
|
|
| EP-WKR-003 | Worker retry exhaustion | repeated retriable failure | category from source; terminal state | capped then no | explicit failed status + error detail | met | implemented in Step 2; keep regression coverage |
|
|
| EP-UI-001 | UI upload action failure | surfaced AppError or fallback exception | category-based safe user message | category-driven | title + message + suggestion + error id | partial | verify consistency on all primary UI actions |
|
|
| EP-LOG-001 | Cross-boundary error logging | missing/uneven fields | n/a | n/a | logs include `error_id`, `category`, `operation`, ids when available | partial | complete in Step 6 (CF-B2) |
|
|
|
|
---
|
|
|
|
## Verification Targets (Step 6/7)
|
|
|
|
1. Every critical path has category + retriable policy defined.
|
|
2. API/UI behavior remains safe and actionable.
|
|
3. Worker terminal failures are explicit and persisted.
|
|
4. Logging fields are consistent at critical handoffs.
|
|
|
|
---
|
|
|
|
## Evidence Links
|
|
|
|
- Step 2 implementation results: `docs/ver1/ver1-step2-results.md`
|
|
- Carry-forward tracking: `docs/ver1/ver1-step1-2-carry-forward-checklist.md`
|
|
- Canonical contract: `docs/error_handling.md`
|