Skip to content

[T-080b] API errors: RFC 9457 problem+json handlers and stable error codes #143

Closed

Description

@CodewithJha

Task T-080b · Milestone M7 — API · Size S · Priority P0 · Epic #7

Implements 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 by type URLs).

Implementation guidance

  • roboprobe/api/errors.py: ProblemDetail Pydantic model (type, title, status, detail, instance, code, errors: list[FieldError], trace_id: str | None) and def install_error_handlers(app: FastAPI) -> None.
  • Mapping table ERROR_MAP: dict[type[RoboProbeError], tuple[int, str]] built from the hierarchy in core.errors (T-002b) — codes exactly as doc 12 §1.1: VALIDATION_ERROR 422, NOT_FOUND 404, CAMPAIGN_INVALID_TRANSITION 409, SPACE_INVALID 422, BACKEND_UNSUPPORTED_PARAM 422, NO_WORKERS 409, PRECONDITION_FAILED 412, UNAUTHORIZED 401, INTERNAL 500.
  • RequestValidationError → 422 VALIDATION_ERROR with errors[].pointer as RFC 6901 JSON pointers (/budget) built from Pydantic loc.
  • type = f"{settings.api.error_type_base}#{code.lower().replace('_','-')}"; api.error_type_base (new) defaults to the repo's docs/errors.md URL; docs/errors.md has one heading per code so anchors resolve.
  • Unhandled exceptions: log api.unhandled with stack (server side only), respond 500 INTERNAL with trace_id; never include exception text.
  • media_type="application/problem+json"; register OpenAPI responses for 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[].pointer correct for nested fields (e.g. /strategy/params/epsilon).
  • docs/errors.md anchors match type URLs (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 Unreleased updated 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.py
  • docs/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

No one assigned

    Labels

    area:apiREST + SSE API (FastAPI)milestone:M7M7 — APIpriority:P0Critical path / blocks otherssize:S<= 1 daytaskChild task of a milestone epictype:featureNew functionality

    Projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions