postMessage API inconsistency

Description

Per looking at this example in the documentation of the Web API, I expected my callback to have been called with an Error as the first argument if there’s an issue.

Expected result:

The err callback arg to have been populated with an Error.

Actual result:

The response callback arg is called with an “error data structure”.

Although I had an error handler in place, after a little bit of trial an error, I determined that the success handler was instead being called with the following: { ok: false, error: 'channel_not_found' }.

For what it’s worth, I triggered the above error scenario (trying to publish to a channel that doesn’t exist) to double-check that my logging was working as expected.

Specifically, I’m wrapping webClient.chat.postMessage in a promise and, upon success, I’m acknowledging a message on a queue as processed. However, like mentioned above, I was erroneously acknowledging because I’d expected the error argument to have been provided.

I guess my question is this – I feel like, from an API perspective, I should be handling one scenario or the other. In other words, if the error is always going to be contained within the response argument as an error data structure, then the callback only needs to have one param provided. Conversely, the library could invoke the callback with an Error if the response isn’t successful. But, as of right now, I’m having to handle both possibilities:

    // ... other code
    return new Promise((resolve, reject) => {
      webClient.chat.postMessage(channel, text, {
        as_user: true,
        attachments,
      }, (err, response) => {
        // NOTE: The following two lines specifically.
        const { error } = response;
        if (err || error) return reject(err || error);
        return resolve(response);
      });
    });

I guess I just more or less wanted confirm that this is as-intended from a design perspective, because it definitely caught me off-guard and sent me on a little 5-minute debugging detour! 😄

[aoberoi]

Hey @dsimmons, thanks for providing a detailed recount of your experience. This sort of thing really helps us understand where the rough edges are.

I agree that you shouldn’t have to check both the truthiness of the error parameter and the truthiness of the ok property before deciding there was an error. I’ll mark this as a bug so we can fix that.

One thing I noticed is that you said you were wrapping the API call in a Promise, but you should know that when you don’t pass in a callback, we already return a Promise. That might save you some time.

[DEGoodmanWilson]

🙇 It is our pleasure!