User friendly error messages

[Tunous]

The way TootSDK currently works is that when it encounters errors during API calls it wraps them inside of TootSDKError and throws. This based on my experience most commonly results in invalidStatusCode case being thrown. I implement error handling by either handling this case and searching for http status codes I know how to handle or fallback to showing generic error with localized description displayed to user. Unfortunately I noticed that is not the best approach as it usually results in “Invalid HTTP status code” message being displayed.

For example, recently I attempted to upload post with both video and images as attachments. Apparently this case is not supported and Mastodon responded with http 422. This resulted in my app showing mentioned invalid status code message. But in the logs from response I saw below error:

{
  "error": "Nie możesz załączyć pliku wideo do wpisu, który zawiera już zdjęcia"
}

Translating from polish it exactly describes what happened: that you can’t upload videos together with images. Now that is a message I would like to see displayed in the app.

I’m opening this issue to suggest improving error handling in the SDK to make it possible to display errors from API like this one to the user.

[kkostov]

@Tunous thanks for raising the issue.

Some initial thoughts about this, just a brain dump:

• The server error responses are non-standard (outside the API spec) and different between fedi flavours and even endpoints. (e.g. http code 422 may or may not be accompanied by a friendly message and the message may be different).

I think there are several aspects we can try to improve:

• We can always include the http status code (we already do with the http response, but maybe make it easier to access).

In the example above, error 422 can already indicate that the content/request is not correct. What exactly is wrong of course may or not be available as information. To that end, we can:

• Extract a message field that we can try to deserialize from the payload (e.g. we can look for error or messsage or just plain text response to put in there).

The caveat here is this is still probably not enough to make it into an actionable message to be shown to the user as is, and sometimes even the server response is not specific or just a 503. An app should not be showing these errors verbatim.

• We can research mapping known validation errors to enumeration keys which the client app can use to offer the correct course of action (it's not always a message, maybe the app can solve it programmatically without bothering the user).

• Known validations like that one you raised (mixing video + images in a post) can be added as client-side validation for specific flavours, so we'd prevent the request much sooner and allow the app to inform the user what's up.