My biggest wish: predictable, simple, idiomatic, well-documented error handling

[jgehrcke]

Great to see a lot of movement here! :-)

Let's talk error handling (see below for why I think that's critically important for the success of a client library)! 🔥

I would love to see the problem described in aws/aws-sdk-js#2611 solved really cleanly, and I would love to see an "error handling" section in the main README of this library, discussing

• which kinds of errors I can expect to be thrown, and how to catch them with precision (preventing over-generalized error handlers).
• to which degree transient errors (on TCP level, but also on layer 7) are handled internally by the library (e.g., via retrying), and how I can influence that behavior as an application developer.

In addition to that, I would love to see an exhaustive chapter on error handling in the lines of what boto (from the Python ecosystem) has: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/error-handling.html.

With version 3 of the library, I would love to see a clear declaration of intent that a call either succeeds or throws an error, i.e. that any other state would be considered a bug. In fact, with version 2 of the library we sometimes seem to have to deal with these intermediate states where no error is thrown (when using .promise()) or returned (when using callbacks), but the result object still indicates a problem (via being falsey, or having certain properties undefined).

As per the nature of the communication involved (across machine boundaries) there also need to be pretty clear docs on timeout constraints (tcp connect() and recv() timeouts), how to configure them, and how timeout errors are exposed to application developers.

Why is that important?

Remote procedure calls (HTTP API calls) fail all the time for a plethora of reasons. Application code needs to deal with that. In my distributed systems experiences one of the most common root causes for bugs has to do with insufficient, inconsequential, or plain buggy error handling code.

These AWS articles cover the surface of this topic:

• https://docs.aws.amazon.com/AWSEC2/latest/APIReference/errors-overview.html
• https://docs.aws.amazon.com/general/latest/gr/api-retries.html

When trying to build a robust system using a client library like this here then of course it's important to know how this library handles remote procedure call errors. It's especially important to understand precisely how it exposes these errors to the application developer, and how the application developer is then recommended to deal with those errors.

These points are ideally addressed by 1) a sound and complete error handling strategy in the library, and 2) super good documentation :-).

Individual developers shouldn't discover best practices and paradigms by themselves, they should be able to discover those best practices in docs.

I must say that this topic turned out to be a bit of a disaster for me in the context of aws-sdk-js (v2). The topic of error handling (no offense) seemingly didn't get all the love it should have gotten in aws-sdk-js (v2) and its docs. My sincere wish for the community is that aws-sdk-js-v3 does much better on this front! In particular, aws/aws-sdk-js#2611 really was a downer for me (but I tried to contribute constructively, cf. my comments in that thread). Also, for v2 I could not find decent "recommended way to handle errors" code snippets, but only ever boring console.log(error) examples.

Thanks for all the efforts and for consideration!

[trivikr]

Related #1506

[AllanZhengYP]

Hi @jgehrcke

We recent refactored our error handling and generates error in concrete classes. You can read about it in our blog: Error Handling in Modular AWS SDK for JavaScript (v3). Hopefully it addresses all your questions. If you have more feedbacks, please open a new issue.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs and link to relevant comments in this thread.