Point out that the token must have write scope

src/huggingface_hub/utils/_errors.py

@@ -357,6 +357,15 @@ def hf_raise_for_status(response: Response, endpoint_name: Optional[str] = None)
             )
             raise BadRequestError(message, response=response) from e
 
+        elif response.status_code == 403:
+            message = (
+                f"\n\n{response.status_code} Forbidden: {error_message}."
+                + f"\nCannot access content at: {response.url}."
+                + "\nIf you are trying to create or update content,"
+                + "make sure you have a token with the `write` role."
+            )
+            raise HfHubHTTPError(message, response=response) from e
+
         # Convert `HTTPError` into a `HfHubHTTPError` to display request information
         # as well (request id and/or server error message)
         raise HfHubHTTPError(str(e), response=response) from e

tests/test_utils_errors.py

@@ -49,6 +49,19 @@ def test_hf_raise_for_status_401_repo_url(self) -> None:
         self.assertEqual(context.exception.response.status_code, 401)
         self.assertIn("Request ID: 123", str(context.exception))
 
+    def test_hf_raise_for_status_403_wrong_token_scope(self) -> None:
+        response = Response()
+        response.headers = {"X-Request-Id": 123, "X-Error-Message": "specific error message"}
+        response.status_code = 403
+        response.request = PreparedRequest()
+        response.request.url = "https://huggingface.co/api/repos/create"
+        expected_message_part = "403 Forbidden: specific error message"
+        with self.assertRaisesRegex(HfHubHTTPError, expected_message_part) as context:
+            hf_raise_for_status(response)
+
+        self.assertEqual(context.exception.response.status_code, 403)
+        self.assertIn("Request ID: 123", str(context.exception))
+
     def test_hf_raise_for_status_401_not_repo_url(self) -> None:
         response = Response()
         response.headers = {"X-Request-Id": 123}