SendEmailAsync does not document AmazonSimpleEmailServiceV2Exception

[lonix1]

Describe the issue

I'm using SES v2.

I used SendEmailAsync with an identity that has a default configuration set. The policy was not correct and so prevented my app from sending the mail:

This exception was thrown: AmazonSimpleEmailServiceV2Exception:

Amazon.SimpleEmailV2.AmazonSimpleEmailServiceV2Exception: User 'arn:aws:iam::000000000000:user/foo' is not authorized to perform 'ses:SendEmail' on resource `arn:aws:ses:region:000000000000:configuration-set/bar'

That exception is not documented - neither in the API docs nor in the doc-comments that show in my IDE.

Links

https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SimpleEmailV2/MSimpleEmailServiceV2SendEmailAsyncSendEmailRequestCancellationToken.html

[lonix1]

Also, that is probably not the right exception to throw in the case of a misconfiguration. A misconfigured app could send 1000s of emails before the problem is identified by a human operator.

It's a catch-all exception - "Common exception for the SimpleEmailServiceV2 service." - so the app has no way to differentiate between config errors and other errors.

[ashishdhingra]

@lonix1 Good morning. The mentioned exception is thrown by the incorrect policy configuration per your issue description. It is the IAM issue, not SES issue. In fact any service would throw this exception if the IAM policy does not allow a role or service to invoke certain service API operations. Hence, such exceptions are not documented in specific service (in this case SES) API page. The page SESv2 > Common Errors lists the errors common to the API actions of all AWS services. It specifically states that For errors specific to an API action for this service, see the topic for that API action.. The AWS .NET SDK (or any other language SDK) and it's respective service API documentation are generated from models shared by AWS services (refer here).

In your use case, policy was misconfigured and hence it caused IAM exception which is returned as AmazonSimpleEmailServiceV2Exception since you are invoking SESv2 API operation.

Thanks,
Ashish

[lonix1]

Thank you for explaining that, I now understand the .NET SDK's error handling philosophy. 👍

However it should be noted:

• If there are more exceptions than those listed on the SendEmailAsync page, then at the very least, there should be a link from that page to the other page. Right now that page reads as if the exception list is definitive, and it is not. That is a recipe for trouble for developers.
• The idea that there are multiple sets of exceptions that can be thrown for any given API call, and that they are documented in different places without links between them, is very surprising in .NET. The idiomatic .NET way of documenting exceptions, is that all exceptions possible for any given API method are documented in one place. As a practical solution to this issue, there could be a link from the one page to the other.
• In none of the pages we've discussed, does AmazonSimpleEmailServiceV2Exception appear. So it's a "hidden" error.

We've already worked around these issues. But take into account other devs may have their code blow up one day, and they won't understand why. It would be because they built their systems around one set of exceptions, and there are many more they don't know about.

[ashishdhingra]

@lonix1 Tysnks for the suggestions. For specific error wrapped by AmazonSimpleEmailServiceV2Exception, you may inspect InnerException property.

Regarding documentation issue, all SDK(s) rely on service models (not just .NET SDK). Until and unless there is some information in these models to include common exceptions, it's not feasible to have these linked from API reference pages. I would discuss with relevant teams on how to further improve documentation as you suggested.

Thanks,
Ashish

[github-actions]

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.