[vprashrex]

Issue

Closes #834

Summary

Status codes now mean the same thing across endpoints, every error is reported once with the route and tenant on it, and a Celery task stays in the same trace as the request that started it.

Error responses

request fails
  IntegrityError       -> db_error_handler          23505 → 409, 23503 → 422, else 500
                                                      client: short message; constraint name → logs + Sentry tag only
  HTTPException        -> http_exception_handler    registered on Starlette's base class, so 404/405 also use APIResponse
  any other Exception  -> generic_exception_handler  500, no exception text in the body, one Sentry event (logger.error only)
every handler          -> tags http.route / http.method / http.status_code / error.class, transaction "METHOD /route"

Status code fixes

Where	Before	After
Credential encrypt / decrypt failure	ValueError → 500	502, "Retry shortly."
Delete credentials that don't exist	500	404
Missing provider / credential in request	ValueError → 500	400
Duplicate credential / config / version	per-call 400 or 500	409 from the central DB handler
Delete an already deleted collection	400	409
Unreadable document format (doc transform)	400	422

Observability

 api request
   llm.start_job
     apply_async
-      (manual inject/extract)  → worker spans reparented to the request, Sentry split them into separate transactions
+      run/run_llm_job          → CeleryInstrumentor parents it; one trace end to end
 celery task_prerun
+  tags celery.task_name, tenant.project_id, tenant.org_id (strings) from task kwargs
 log levels
-  4xx from the client side (LLM job HTTPException, send_callback failures) logged as error
+  logged as warning; 5xx stay error
 sentry
-  profiling, Redis tracing (Redis is still used; only its spans are gone)
+  gen_ai.input.messages / gen_ai.output.messages masked like the other GenAI content keys

Docs updated: docs/wiki/cross-cutting/exceptions.md, docs/wiki/cross-cutting/observability.md, the observability and LLM-call architecture docs, .claude/conventions/celery.md.

Evidence

• Before: a duplicate credential returned 400 or 500 depending on the call site; a crypto failure returned 500 with the exception text; a bot hitting an unknown path got FastAPI's {"detail": "Not Found"}; each LLM job showed up in Sentry as two transactions (request, worker) and callback 401s were error-level alerts.
  After: checked live against a personal Sentry project:
  • one trace http.server → llm.start_job → apply_async → run_llm_job → chat → provider.execute
  • tenant tags present as strings on API and worker spans
  • no Redis spans, no profiles
  • bot 404 returns the APIResponse shape
  • callback and config errors arrive as warnings
  • a 500 carries the transaction and route
• Tests: test_exception_handlers.py (DB handler 409/422/500, generic handler captures once, 404/405 shape), credentials, config, version, onboarding, security, collection and tracing tests updated or added. CI checks (3.12) passes.

Merge Danger

Door: two-way

Revert restores the old handlers and status codes; there are no migrations and no data changes.

Blast Radius: API clients

• Clients that branch on status codes see new values: 409 instead of 400/500 for duplicates, 404 instead of 500 for missing credentials, 422 instead of 400 for unreadable documents, 502 instead of 500 for credential crypto failures.
• Sentry: Redis spans and profiles stop; LLM jobs now appear as one transaction instead of two, so per-transaction counts drop.
• codecov/patch is below target on this PR; everything else in CI passes.

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one): 1

• ready-for-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: ProjectTech4DevAI/kaapi-backend
• Branch: fix/834-status-code-consistency
• File: .coderabbit.yaml
• Commit: a8f5863
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: afd0dbc8-7bd1-4fd6-adb0-ea85efbd64d4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

OpenAPI changes   ⚪ No API surface changes

Note

This PR does not modify the API contract.

_{main ↔ 65c04273 · generated by oasdiff}

[codecov]

Codecov Report

❌ Patch coverage is 99.77064% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
backend/app/core/telemetry/llm.py	85.71%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[AkhileshNegi]

can you take a look at this? why we need this?