... then we do not need the details link anymore at all. This problem is more complicated than it appears though. Currently, the "default" error messages are pretty useless most of the time because they are quite generic. The detailed messages, however, can be quite technical which is appropriate since they should expose as much detail as possible about an error. Additionally, the detailed messages are not intended to be localized.
I guess the proper solution would be to improve the quality and increase the number of "default" error messages. These, for example, may contain advise about how to solve an issue. The back-end error messages are meant to only report an error including technical information that does not have an actual use for regular users (unless they want to file a bug report).

Agreed. We however seem to have way too many cases where we have common errors with a too technical error message that is in addition also not expanded by default.

So the steps here imho would be:

• get a list of common and bad error messages
• improve error message text for those
• remove details link to always show complete error message

I totally agree to the arguments given by Henning and Lydia. I suggest to close this report (or make it a tracking bug) and create new reports for the most common untranslated error messages that should be improved.

Let's collect that list here. No need for a new one imho.

The API already provides localized errors in some cases. I suggest to show that localized error in full if it exists. The structured returned by the API will look something like this:

{
  "error": {
      "code": "invalid-snak-value",
      "info": "Malformed URL: asldkjf",
      "messages": {
          "0": {
              "name": "wikibase-validator-bad-url",
              "type": "error",
              "parameters": [
                  "asldkjf"
              ]
          },
          "html": {
              "*": "<p>Malformed URL: asldkjf\n</p>"
          }
      }
  }
}

So, if result[error][messages][html] is defined, we can just show it, it's intended for the user.

If that is not set, we will only have a "traditional" API error:

{

"error": {
    "code": "invalid-guid",
    "info": "Invalid claim guid"
}

}

In that case, we should do what we do now: show a localized message based on the code, and show what's in "info" under "details".

Not that the error info is, by convention, not localized. This is the first parameter passed to dieUsage(), and we should double-check that we don't localize it (e.g. it seems we are returning a localized message for invalid edit tokens).

The error info should be treated as a plain value (html escaping must be applied). Linebreaks may be significant and should be preserved (using <pre> or <br/>): in some cases, the error info will contain a stack trace (at least if wgShowExceptionDetails is enabled).

After some more discussion, especially with Adrian, and some more consolidation in the API code as well as changes to the core API, where's what I now think:

First of all, consider that the caller (the UI) usually knows best what the user was trying to do, while the responder (the server) knows best what went wrong. Also, let's assume that the purpose of haven a "details" section which is hidden per default is mainly to provide technical information to bug reports.

Following this, I believe error dialogs should consist of three parts:

1. A title, provided by the UI code, briefly indicating what action was being performed ("Error while saving a sitelink", "Error while tweaking the frob").
2. An error message indicating the problem, as reported by the server. This should be taken from the response.error.messages[*].html field in the API response if present. If not present, we could either use the English message from response.error.info, or provide a localized message based on response.error.code.
3. A details section, collapsed per default, containing (in small, monospace type):
   • The request URI and POST data (with any tokens stripped)
   • The full response JSON
   • user groups (possibly also user name and/or id)
   • data/time
   • software version(s) (if we can easily do this)

For reference, an error response from the API:

"error": {
    "code": "no-such-entity",
    "info": "Could not find such an entity (Invalid id: asdfasdf)",
    "messages": [
        {
            "name": "wikibase-api-no-such-entity",
            "parameters": [],
            "html": {
                "*": "Could not find such an entity"
            }
        }
    ],
    "*": "See https://www.wikidata.org/w/api.php for API usage"
}

The example isn't perfect (that message should actually have the bad ID as a parameter, and the message could be more specific), but it should serve the purpose here.

I wonder if we need the in-the-interface split between normal and expanded anyway – currently, most errors I know have the useful and short stuff in the expand part so we could try to show normal and expanded part without a visible division.

As far as I'm aware of what I said still applies in many cases: Not all error messages (below the expand button) are translated. I suggest to remove the expand button but keep the (tiny) visual difference between the two. Maybe make it a bit prettier?

@thiemowmde Translated and untranslated error messages are returned from the API using different mechanisms. They are easy to distinguish.

There is basically three cases:

• delivery failure: the API response is not even valid JSON, it's HTML or something. Or just a timeout, with no data at all.
• technical error: the API responds with an untranslated plain text error (in $data['error']['code'])
• user error: the API responds with a translated and rendered(!) plus structured data for error key and params in $data['error']['messages'][...]['html']['*']

I would suggest to use the old form (generic message with a "details" button) for delivery and technical errors. For user errors, just show the message you get from the API, with no additional generic message and no split.

There are three code paths that extract a "detailed message" from the API response, see https://github.com/wikimedia/mediawiki-extensions-WikibaseJavaScriptApi/blob/master/src/RepoApiError.js#L93. The last two should stay as they are. Technical, untranslated, maybe not expandedd by default. But the first should replace the generic error message, as you suggested.

does this mean that is easy to find out which type of message was received (as frontened) and that triggering the collapsed vs. expanded based on this (or anything else) it not a problem?

@Jan_Dittrich it's easy to distinguish them, but I don't know how easy it is to pass this distinction on to the bit of code that actually shows the message.

@daniel OK, that we can investigate.

We picked this for the current sprint. We said we want to split this into two very small tickets:

• Remove collapsing.
• Reword the unspecific default message and make it very short and to the point.

That is what it currently looks like.

• An error occurred
• Make the detail text look like the other (sans-serif, "An error occ…") text.

The comments T54843#540706 by @Lydia_Pintscher as well as T54843#2515169 by myself list acceptance criteria, which are all met by now. Therefor I'm going to close this ticket as resolved.

This does not mark the end of possible improvements for the "display of API error messages in the UI". For example, we want to make error messages addressable and pop up at the exact field/widget in the UI where the error happened. But this is for an other ticket, see T138748: [Solution] Value checking and saving: Error messages, no silent fails.