boto3.client("s3").head_bucket does not throw NoSuchBucket as per documentation

[anentropic]

Describe the issue

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/head_bucket.html

Exceptions

• S3.Client.exceptions.NoSuchBucket

But this exception is never raised.

Instead you get:

botocore.exceptions.ClientError: An error occurred (404) when calling the HeadBucket operation: Not Found

This previous issue was closed as won't fix because behaviour of underlying S3 API meant it was not possible to raise a custom exception.

But surely in that case the custom exception definition should be removed and documentation updated?

Links

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/head_bucket.html

[tim-finnigan]

Hi @anentropic thanks for reporting this issue. I would agree that the current documentation here is misleading. Unfortunately the documentation for head_bucket is auto-generated by models provided by the S3 service team, and as mentioned in the previous issue you referenced, it would be a breaking change to update the error at this point.

However, I think there is still an opportunity here to better clarify the documentation and add an explanation for this. Since service documentation models are used across SDKs, I created an issue for this in our cross-SDK repository: aws/aws-sdk#726. I'll reach out to the S3 documentation team for feedback and update the issue. Please refer to that issue for updates going forward.

Also for further clarification on exceptions/error handling see: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/error-handling.html#aws-service-exceptions

AWS service exceptions are caught with the underlying botocore exception, ClientError. After you catch this exception, you can parse through the response for specifics around that error, including the service-specific exception.

[github-actions]

This issue is now closed. Comments on closed issues are hard for our team to see.
If you need more assistance, please open a new issue that references this one.