diff --git a/scripts/forgejo_set_actions_secret.py b/scripts/forgejo_set_actions_secret.py
index 90eafed..d3a0538 100644
--- a/scripts/forgejo_set_actions_secret.py
+++ b/scripts/forgejo_set_actions_secret.py
@@ -374,8 +374,15 @@ def main() -> int:
         status = getattr(e.response, "status_code", None)
         url = getattr(e.response, "url", "")
         body = ""
+        required_scopes: List[str] = []
         try:
             body = (e.response.text or "").strip()
+            if body:
+                parsed = e.response.json()
+                scopes = parsed.get("message", "")
+                m = re.search(r"required scope\(s\):\s*\[(?P<scopes>[^\]]+)\]", str(scopes))
+                if m:
+                    required_scopes = [s.strip() for s in m.group("scopes").split(",") if s.strip()]
         except Exception:
             pass
 
@@ -386,6 +393,11 @@ def main() -> int:
             )
             if body:
                 print(f"Response body: {body}", file=sys.stderr)
+            if required_scopes:
+                print(
+                    "Missing token scope(s): " + ", ".join(required_scopes),
+                    file=sys.stderr,
+                )
             print(
                 "This usually means your Forgejo personal access token does not have sufficient permissions, "
                 "or your Forgejo instance does not allow managing user/org Actions secrets via the API.\n"
@@ -394,7 +406,7 @@ def main() -> int:
                 "- Or use repo-scoped secrets with: --scope repo --repo owner/repo\n",
                 file=sys.stderr,
             )
-            raise
+            return 2
         raise
 
     if args.update_vault_both_public_keys: