[FEATURE REQUEST] CLI could be more helpful about some kinds of API responses

[iximeow]

Is your feature request related to a problem? Please describe.

fastly CLI operations failed for me in ways that made no sense (404s configuring a service that has existed for years, etc), and it took me a moment to figure out it was because I had unwittingly used the wrong token.

Describe the solution you'd like

The CLI suggests "If you believe this error is the result of a bug, please file an issue", but for example cases like "404 on PUT /service/<service_id>" are probably not returning 404 as a bug but as a result of the service not existing or provided API token not being able to manage that service.

The CLI offers basically exactly the advice that would have helped me but only for 401 and 403 responses. for some known API paths (is there an OpenAPI document for the Fastly API? I don't remember) this would definitely have helped me too.

Describe alternatives you've considered

#894 describes the API's somewhat minimal 404 "Cannot find ..." as there being a bug ticket to track a fix. I imagine that the experience of operating on a service you can't access wouldn't substantially change from the API PoV - you don't want to inadvertently disclose a service ID to be valid or the scope on a token, after all - but maybe there's something there.

or maybe no change to the CLI after all 🤷‍♀️

Additional context

in addition to my own, this probably would have helped (or at least been the same advice Fastly offers, without the round trip) in many of the following cases:

#1780
#1237 <-- don't know for sure since there was no followup from OP, but this was the advice to the issue-filer
#1256 <-- from the same author, this was the issue
#894
#793 <-- educated guess given 404 on a fresh fastly profile create...

[kpfleming]

Yes, this is a complicated area. The CLI doesn't have any information of its own, so if the API doesn't provide any details in the response there isn't anything we can tell the user. In the particular case of 404 it is (as you suggested) often used to mask the existence of resources which do exist but for which the provided token does not have permission to execute the operation. This problem is going to happen more often, not less often, as the permission-based RBAC system is rolled out across the Fastly system. Given that, I think it would be reasonable to add a NotFoundRemedation error type with some suggestions for possible causes.

There is no published OpenAPI document, unfortunately.