Log unmapped API errors (#288)

[leynos]

Summary

This branch closes #288 by logging every unmapped domain exception that becomes
an HTTP 500 response through the centrally managed logging port. It also fixes
the Python 3 exception-clause syntax in the serializer, documents the
request-level logging boundary, and adds direct regression coverage.

Closes #288.

Review walkthrough

• Start with episodic/api/errors.py for the logging-port binding, the three unmapped fallback records, and the syntax repair.
• Then review episodic/api/resources/init.py for the deliberate per-handler logging deferral.
• Finish with tests/test_api_errors.py for the fallback-envelope and traceback-enabled log assertions.

Validation

• make check-fmt: passed.
• make lint: passed; the dedicated runner intermittently lost the final Skylos child, so the identical foreground Skylos command also completed with exit code 0.
• make typecheck: passed.
• make test: passed, 1,230 passed and 3 skipped.
• make markdownlint: passed.
• make nixie: passed.
• coderabbit review --agent: two actionable maintainability findings were addressed; the final two refactoring suggestions were declined as they would obscure the intentionally distinct mapper contracts and conflict with the repository's meaningful-test-documentation guidance.

References

• Lody session

Summary by Sourcery

Add diagnostic logging for unmapped API errors while preserving their internal-error responses.

Bug Fixes:

• Log unmapped profile/template, reference, and source-intake domain errors before returning HTTP 500 responses, including traceback information.

Enhancements:

• Clarify that mapped API errors are deferred to request-level logging and that resource handlers do not emit per-handler logs.

Tests:

• Add regression coverage verifying fallback HTTP envelopes and centrally routed error records for each API error mapper.

Chores:

• Correct the exception-clause syntax in the API error status helper.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Warning

Your free Security trial is over. An organization admin can activate billing to continue.

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

The PR adds centralized, traceback-enabled logging to all API error mapper fallbacks that produce HTTP 500 responses, documents the deliberate request-level logging boundary, fixes Python 3 exception syntax, and verifies the behavior with focused regression tests.

Sequence diagram for unmapped API error logging

sequenceDiagram
    participant Handler as API handler
    participant Mapper as Error mapper
    participant Logger as Central logging port
    participant Falcon as Falcon response

    Handler->>Mapper: map_profile_template_error(exc, entity_id)
    Mapper->>Logger: log_error(logger, message, ..., exc_info=True)
    Mapper-->>Falcon: HTTPInternalServerError
    Falcon-->>Handler: HTTP 500 response

Loading

Sequence diagram for mapped API error request boundary

sequenceDiagram
    participant Handler as API handler
    participant Mapper as Error mapper
    participant Falcon as Falcon response
    participant RequestLog as Request-level logging

    Handler->>Mapper: map_reference_error(exc, context)
    Mapper-->>Falcon: mapped HTTP 400/404/409 response
    Falcon-->>Handler: HTTP response
    Handler->>RequestLog: defer request-level logging

Loading

File-Level Changes

Change	Details	Files
Log unmapped domain exceptions that fall through to HTTP 500 responses via the centralized logging port.	Bind a module logger through the shared logging helpers. Add traceback-enabled error records to the profile/template, reference, and source-intake fallback branches. Preserve each mapper’s existing HTTP 500 response and envelope behavior.	episodic/api/errors.py
Clarify that request-level logging remains intentionally deferred from individual resource handlers.	Document the logging boundary and planned correlation middleware location. Keep resource handlers free of per-handler logging.	episodic/api/resources/__init__.py
Add regression coverage for fallback responses and emitted diagnostics.	Test all three unmapped exception paths for HTTP 500 and internal-error envelopes. Verify exactly one centralized error record per path, including traceback information and safe contextual fields.	tests/test_api_errors.py
Repair exception handling syntax for Python 3 compatibility.	Update the status-code fallback clause to valid Python 3 syntax.	episodic/api/errors.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#288	Log every unmapped domain exception in the API error mappers at ERROR level, with traceback information, through the centralized logging port before returning an HTTP 500 response.	❌	The PR adds the required logging calls and regression tests for all three mapper fallbacks, but episodic/api/errors.py still contains the invalid Python 3 syntax except IndexError, ValueError:. As a result, the module cannot be imported or executed, so the logging implementation is not functional until that clause is changed to a valid tuple form.
#288	Deliberately define and document the logging boundary for API resource modules, leaving per-handler logging deferred when request-level middleware is the appropriate location.	✅

Possibly linked issues

• episodic/api/errors.py and episodic/api/resources/* emit no log lines at all #288: The PR directly addresses issue 288 by logging all unmapped API errors becoming HTTP 500 responses and documenting resource logging boundaries.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[codescene-access]

No quality gates enabled for this code.