refactor(api): Stop masking refresh-token service errors as 401

[QuantumGhost]

AI disclosure: This PR was primarily drafted with Codex using GPT-5.4. I have reviewed and edited the final diff, and I am responsible for the content.

Important

1. Make sure you have read our contribution guidelines
2. Ensure there is an associated issue and you have been assigned to it
3. Use the correct syntax to link this PR: Fixes #<issue number>.

Summary

Fixes #38462.

Related to #38457.

This change narrows the error handling in POST /console/api/refresh-token and replaces the remaining string-based validation detection with dedicated exception types.

What changed:

• keep the explicit 401 response when the refresh-token cookie is missing
• define dedicated service-layer exceptions for the two current refresh-token validation failures:
  • RefreshTokenNotFoundError
  • RefreshTokenAccountNotFoundError
• raise those dedicated exceptions from AccountService.refresh_token(...)
• catch those dedicated exceptions, plus the existing Unauthorized path from banned-account loading, in the controller and map them to 401
• allow unexpected ValueError instances and operational failures such as runtime/Redis errors to propagate instead of being rewritten as 401
• update the focused unit tests to distinguish expected 401 validation failures from unexpected exceptions that must continue to bubble up

Why:

• the earlier broad catch masked backend failures as authentication failures
• the intermediate string whitelist on ValueError was narrower, but still encoded auth semantics in exception messages
• dedicated exception types keep the same intended HTTP behavior while making the controller contract explicit and less fragile

Validation:

• uv run --project api pytest -o addopts='' api/tests/unit_tests/controllers/console/auth/test_token_refresh.py

Screenshots

Before	After
N/A	N/A

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran make lint && make type-check (backend) and cd web && pnpm exec vp staged (frontend) to appease the lint gods

From Codex

[github-actions]

Pyrefly Type Coverage

Metric	Base	PR	Delta
Type coverage	52.38%	52.37%	-0.01%
Strict coverage	51.89%	51.89%	-0.01%
Typed symbols	32,084	32,087	+3
Untyped symbols	29,441	29,450	+9
Modules	2970	2970	0

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-07-06 08:19:01.732021381 +0000
+++ /tmp/pyrefly_pr.txt	2026-07-06 08:18:52.472972359 +0000
@@ -1,3 +1,5 @@
+ERROR Argument `str | None` is not assignable to parameter `message` with type `bytearray | bytes | str` in function `controllers.common.fields.SimpleResultMessageResponse.__init__` [bad-argument-type]
+   --> controllers/console/auth/login.py:363:71
 ERROR Argument `SimpleNamespace` is not assignable to parameter `dataset` with type `Dataset` in function `dify_vdb_alibabacloud_mysql.alibabacloud_mysql_vector.AlibabaCloudMySQLVectorFactory.init_vector` [bad-argument-type]
   --> providers/vdb/vdb-alibabacloud-mysql/tests/unit_tests/test_alibabacloud_mysql_factory.py:42:38
 ERROR Argument `SimpleNamespace` is not assignable to parameter `dataset` with type `Dataset` in function `dify_vdb_alibabacloud_mysql.alibabacloud_mysql_vector.AlibabaCloudMySQLVectorFactory.init_vector` [bad-argument-type]

[hjlarry]

LGTM