Enhance error messages for "Invalid JSON Response" errors

Feature Description

The Site Kit API client on the frontend uses @wordpress/api-fetch under the hood which is a layer on top of window.fetch which is designed for interacting with the WordPress REST API. One of the features it provides is to eliminate some of the boilerplate of making fetch requests, such as resolving the JSON body from the response.

The client doesn’t force a JSON response, but it does assume one by default (this can be controlled with an option). In the event that the response is not JSON-parseable (and by default attempts to parse it as such), the client will throw a generic (and very familiar looking) invalid_json error.

This is not particularly useful to the average end user and often leads to support requests which are difficult to provide good support for due to the limited information. Accordingly, we should enhance our error handling in such cases to provide more useful, or at the very least – less cryptic messaging to the end user, and where possible additional context for support.

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• Site Kit should never display a “The response is not a valid JSON response” error message to the end user as part of its user-facing interface (console messages/logging are fine because this is developer-centric tooling)
• Instead, it should show the following, based on a few other conditions:
  • If the response status code is 504: The service took too long to respond. (see #4504 for reference)
  • TODO: Define other conditions.
  • Otherwise: The service provided an invalid response.
• In all of the above cases, the error should be accompanied with the Retry button implemented via TODO (add issue link here for error notifications MVP issue to implement that).

Implementation Brief

Test Coverage

QA Brief

Changelog entry

[felixarntz]

The ACs newly defined on #4997 cover this issue as well as it’s closely related. Please follow along the other issue going forward, closing this as a duplicate.

[aaemnnosttv]

What do we want to show instead?

@felixarntz I meant to ask you about it, this was just intended to be a starting point so far.

As for what we show instead, it could be contextual similar to #4997 (this is mostly relevant for ReportError anyways I think 🤔 ). Essentially a more useful message for the user that potentially links to some SK docs for troubleshooting.

What should we do if the response is not JSON?

That’s usually the reason for the error in the first place! 😄 Another case though could be corrupted JSON, if for example, a PHP Notice were output right before the otherwise valid JSON response, or even an empty response body would also be invalid – although an HTML response could also raise this error. There are a number of things we probably could do but we could probably improve the end user experience quite a bit with even a small change (again, similar to #4997).