Repository navigation
Description
Task
T-080b· Milestone M7 — API · Size S · Priority P0 · Epic #7Implements FR-API-003
Branch
feat/t-080b-api-errors-rfc-9457-problem— one task = one branch = one PR (doc 32 §6)
Summary
Implement api/errors.py: map RoboProbeError subclasses and request validation errors to application/problem+json exactly per doc 12 §1.1 (type URL, title, status, detail, instance, code, errors[]), 500s include trace_id and never leak internals.
Context / motivation
Consistent errors are required by FR-API-003 and by the dashboard (inline title + detail, copyable trace_id, doc 13 §4).
Scope
In scope
- Error-code → HTTP status table; docs page
docs/errors.md(anchors referenced bytypeURLs).
Implementation guidance
roboprobe/api/errors.py:ProblemDetailPydantic model (type,title,status,detail,instance,code,errors: list[FieldError],trace_id: str | None) anddef install_error_handlers(app: FastAPI) -> None.- Mapping table
ERROR_MAP: dict[type[RoboProbeError], tuple[int, str]]built from the hierarchy incore.errors(T-002b) — codes exactly as doc 12 §1.1:VALIDATION_ERROR422,NOT_FOUND404,CAMPAIGN_INVALID_TRANSITION409,SPACE_INVALID422,BACKEND_UNSUPPORTED_PARAM422,NO_WORKERS409,PRECONDITION_FAILED412,UNAUTHORIZED401,INTERNAL500. RequestValidationError→ 422VALIDATION_ERRORwitherrors[].pointeras RFC 6901 JSON pointers (/budget) built from Pydanticloc.type=f"{settings.api.error_type_base}#{code.lower().replace('_','-')}";api.error_type_base(new) defaults to the repo'sdocs/errors.mdURL;docs/errors.mdhas one heading per code so anchors resolve.- Unhandled exceptions: log
api.unhandledwith stack (server side only), respond 500INTERNALwithtrace_id; never include exception text. media_type="application/problem+json"; register OpenAPIresponsesfor common errors so the generated client types them (T-085c).- Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff
PLR2004); public APIs typed (mypy strict) and documented.
Configuration keys
From the configuration reference (doc 27). Keys marked (new) must be added to the typed settings models and appear in the generated reference (T-003c).
- api.error_type_base (new)
Acceptance criteria
- Error envelope tests for every code in doc 12 §1.1.
- No stack traces in responses.
- Every code in doc 12 §1.1 has a test producing it with the documented status.
-
errors[].pointercorrect for nested fields (e.g./strategy/params/epsilon). -
docs/errors.mdanchors matchtypeURLs (test computes slugs). - Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
- Docs, config reference and CHANGELOG
Unreleasedupdated where behaviour, keys or interfaces changed. - Definition of Done (doc 32 §3) satisfied.
Tests required
tests/api/test_errors.py.
Dependencies
Blocked by: #142 (T-080a), #16 (T-002b)
Blocks: #146 (T-081a), #147 (T-081b)
Parallelization notes
Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:
backend/src/roboprobe/api/errors.pydocs/errors.md
Independent of routers.
Definition of Done
Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-080b (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.
References
Design docs: doc 12 §1.1 · doc 34 §5 · doc 13 §4
Requirements: FR-API-003 (traceability: doc 28)
External:
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsBacklog
Activity
/meta,/metrics, request logging #142CampaignCreatevalidation #147