generated from john/python-template
2.7 KiB
2.7 KiB
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.mddocs/ver1/ver1-step2-results.mddocs/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)
- Every critical path has category + retriable policy defined.
- API/UI behavior remains safe and actionable.
- Worker terminal failures are explicit and persisted.
- 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