Point out that the token must have write scope

[bmuskalla]

In case of an HTTP 403, inform the user that their token might not have the right scope for the action.
As things are today, the HF Hub API only returns 'X-Error-Message': "You don't have the rights to create a model under this namespace" in that case so we have to rely on the HTTP error.

I think a better solution would be for the API to return a proper X-Error-Code in case of entity creation/update + a read-only scoped token but that requires server-side changes first.

Fixes #1653

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 80.70%. Comparing base (c32602a) to head (d5ecd2c).
Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2053      +/-   ##
==========================================
+ Coverage   80.64%   80.70%   +0.06%     
==========================================
  Files          71       71              
  Lines        8519     8522       +3     
==========================================
+ Hits         6870     6878       +8     
+ Misses       1649     1644       -5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Wauplin]

Hey @bmuskalla, thanks for the very clean and concise PR! 🚀

Everything looks good to me except that in case of a HTTP 403 I would raise a generic HfHubHTTPError instead of a BadRequestError. A Bad Request error might be misinterpreted as a HTTP 400 which is not the case here. Regarding the error message I would make it simpler:

message = f"{e}\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

What do you think?

[bmuskalla]

Point taken on the confusing nature of using BadRequestError, changed to HfHubHTTPError.
For the message, I've played a bit more with a real error and ended up using Forbidden+server-side message + the hint.

Example:

Traceback (most recent call last):
  File "/Users/bmuskalla/git/huggingface_hub/play.py", line 5, in <module>
    create_repo(repo_id="bmuskalla/super-cool-model", token=HF_RO_TOKEN)
  File "/Users/bmuskalla/git/huggingface_hub/src/huggingface_hub/utils/_validators.py", line 118, in _inner_fn
    return fn(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^
  File "/Users/bmuskalla/git/huggingface_hub/src/huggingface_hub/hf_api.py", line 3352, in create_repo
    hf_raise_for_status(r)
  File "/Users/bmuskalla/git/huggingface_hub/src/huggingface_hub/utils/_errors.py", line 367, in hf_raise_for_status
    raise HfHubHTTPError(message, response=response) from e
huggingface_hub.utils._errors.HfHubHTTPError:  (Request ID: Root=1-65df9500-64c1f6dd124322f75dae5c8f;b7c328b6-c3fa-47f6-830e-a488fca19cdd)

403 Forbidden: You don't have the rights to create a model under this namespace.
Cannot access content at: https://huggingface.co/api/repos/create.
If you are trying to create or update content,make sure you have a token with the `write` role.

I found this the most readable but it's your call in the end.

[Wauplin]

For the message, I've played a bit more with a real error and ended up using Forbidden+server-side message + the hint.

Sounds good yes! Thanks for iterating on it :)