Graceful handling of API HTTP 4xx responses

[codificat]

Problem statement

I ran a quick test of running thamos on an unsupported platform (FreeBSD), and I received this:

pep@freebsd:~/cli-examples $ thamos advise
2022-04-22 16:13:11,472 [3687] WARNING  thamos: Development dependencies will not be considered during the resolution process - see https://thoth-station.ninja/j/no_dev
2022-04-22 16:13:11,472 [3687] INFO     thamos.lib: Using Pipenv files to manage dependencies located in '/usr/home/pep/cli-examples'
2022-04-22 16:13:11,472 [3687] INFO     thamos.lib: Submitting Pipfile.lock as a base for user's stack scoring - see https://thoth-station.ninja/j/user_stack
2022-04-22 16:13:12,474 [3687] INFO     thamos.lib: Using 'latest' recommendation type - see https://thoth-station.ninja/recommendation-types/
2022-04-22 16:13:12,475 [3687] INFO     thamos.lib: Performing static analysis of sources to gather library usage
2022-04-22 16:13:12,676 [3687] ERROR    thamos: (400)
Reason: BAD REQUEST
HTTP response headers: HTTPHeaderDict({'server': 'gunicorn', 'date': 'Fri, 22 Apr 2022 16:13:13 GMT', 'content-type': 'application/problem+json', 'content-length': '179', 'access-control-allow-origin': '*', 'x-thoth-version': '0.34.13', 'x-user-api-service-version': '0.34.13+messaging.0.16.0.storages.0.71.1.common.0.36.0.python.0.16.9', 'set-cookie': '99770cb82864be05282857f803e02327=b78e61ba4533d9d3918951ac9b762e96; path=/; HttpOnly; Secure; SameSite=None'})
HTTP response body: b'{\n  "detail": "\'freebsd-13.0-RELEASE-amd64\' is not one of [\'linux-x86_64\'] - \'runtime_environment.platform\'",\n  "status": 400,\n  "title": "Bad Request",\n  "type": "about:blank"\n}\n'

I believe that it would be good to provide a more user-friendly error message here; at first look, this might look as a bug in the code (either client or server side), and it might not be clear enough, for this case, that the resolver will not work on this platform and why.

High-level Goals

As a user, I would like to see friendly messages that help me quickly identify the causes of problems that result in "bad requests", so that I can better understand what's happening and how can I proceed.

Proposal description

Provide a friendly message.

At a minimum, it might be enough to present the response body (and potentially relevant header fields) in a nicely formatted way, e.g. for the example above:

Title: Bad Request
Detail: 'freebsd-13.0-RELEASE-amd64' is not one of ['linux-x86_64'] - 'runtime_environment.platform'

Beyond that, it would be helpful to automatically identify a few "expected" or common problems and provide a custom message for them, e.g.

Title: Unsupported platform
Detail: 'freebsd-13.0-RELEASE-amd64' is not one of the currently supported platforms, please see XXX

and potentially point to https://khemenu.thoth-station.ninja/api/v1/ui/#/PythonPackages/get_python_platform or even get its contents and print them nicely.

Additional context

See also thoth-station/user-api#1595 for current inconsistent 400 HTTP responses, depending on what triggered them, as this might be something to keep in mind when implementing the handling on the client side.

Acceptance Criteria

• A user friendly message appears after HTTP 4xx API responses

[codificat]

/sig user-experience
/kind feature
/priority important-soon

[sesheta]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

/lifecycle stale

[mayaCostantini]

/remove-lifecycle stale
/lifecycle frozen