fix: improve error handling on model setup

[Benebo7]

Summary

Improves the error feedback shown to users when setting up a model
connection — both when testing a model and when discovering available
models. Maps common provider failures (bad API key, rate limit) to
clearer, more actionable messages instead of surfacing raw upstream
errors.

Fix

The problem: When a model test or discovery failed, the UI often
surfaced the raw upstream provider error (e.g. a bare 400), which is
hard to interpret and doesn't guide the user toward a fix.

What changed:

• model_connection_service.py

  • _model_test_error now maps a 400 containing "api key" to a
    clear AUTH_FAILED result ("Authentication failed. Check your
    credentials and try again.") instead of a generic 400.
  • The rate-limit message now also hints at insufficient quota or an
    unavailable model, not just a transient throttle.

• model_connections_routes.py

  • preview_connection_models returns a friendlier hint
    ("Try typing the model id manually.") when discovery fails, since
    the next best action is manual entry.

Testing

1. Set up a model connection with an invalid API key → verify the
   error reads as an authentication failure, not a generic 400.
2. Using refresh button on model setup for automatic discover on a non-cataloged provider
   returns 400 with explicit direction
3. Trigger a rate limit (or simulate a 429) → verify the message
   mentions quota / unavailable model.

High-level PR Summary

This PR improves error handling when users set up model connections by mapping common provider failures to clearer, more actionable error messages. When authentication fails with a 400 status code mentioning "api key", the system now returns a specific authentication error instead of a generic message. Rate limit errors now include additional context about possible quota issues or unavailable models. The model discovery endpoint also provides a helpful hint to manually enter the model ID when automatic discovery fails.

⏱️ Estimated Review Time: 5-15 minutes

💡 Review Order Suggestion

Order	File Path
1	surfsense_backend/app/services/model_connection_service.py
2	surfsense_backend/app/routes/model_connections_routes.py

Summary by CodeRabbit

• Bug Fixes
  • Improved connection error messages when model discovery fails, including guidance to enter the model ID manually.
  • More accurately identifies certain API key authentication failures and provides provider-specific guidance.
  • Updated rate-limit messages with clearer troubleshooting information about quotas and model availability.

[vercel]

@Benebo7 is attempting to deploy a commit to the Rohan Verma's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

Model connection error handling now adds a manual model ID hint for discovery failures, classifies API-key-related HTTP 400 errors as authentication failures, and provides expanded guidance for rate-limited verification results.

Changes

Model connection error handling

Layer / File(s)	Summary
Discovery preview fallback guidance surfsense_backend/app/routes/model_connections_routes.py	ModelDiscoveryError responses now include guidance to type the model ID manually.
Verification error classification and messages surfsense_backend/app/services/model_connection_service.py	HTTP 400 errors mentioning an API key now produce AUTH_FAILED results, and RATE_LIMITED messages mention insufficient quotas or unavailable models.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: anishsarkar22

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: improving error handling during model setup.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

surfsense_backend/app/services/model_connection_service.py (1)

123-128: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Fix the rate-limit message wording.

possible insufficient quotas or unavailable model is grammatically unclear. Use wording such as: “check whether your provider quota is insufficient or the model is unavailable.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@surfsense_backend/app/services/model_connection_service.py` around lines 123
- 128, Update the rate-limit message returned by the rate-limit branch in
VerifyResult to use grammatically clear wording, specifically directing users to
check whether their provider quota is insufficient or the model is unavailable.
Preserve the existing status, success flag, and other guidance.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@surfsense_backend/app/services/model_connection_service.py`:
- Around line 123-128: Update the rate-limit message returned by the rate-limit
branch in VerifyResult to use grammatically clear wording, specifically
directing users to check whether their provider quota is insufficient or the
model is unavailable. Preserve the existing status, success flag, and other
guidance.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2de41fbf-9680-48ea-bda9-7d400f6e321d

📥 Commits

Reviewing files that changed from the base of the PR and between 3b319ce and 8eb8d01.

📒 Files selected for processing (2)

• surfsense_backend/app/routes/model_connections_routes.py
• surfsense_backend/app/services/model_connection_service.py

[MODSetter]

@Benebo7 Thanks. Can you please reopen this PR on 'dev' branch.

[Benebo7]

@Benebo7 Thanks. Can you please reopen this PR on 'dev' branch.

My bad