S3.Client.head_object() raises S3.Client.exceptions.ClientError instead of the documented S3.Client.exceptions.NoSuchKey

[valentinoli]

Describe the bug

When calling S3.Client.head_object() and the provided key is not found in the S3 bucket, the function does not raise the expected error type.

Expected Behavior

I expected the function to raise S3.Client.exceptions.NoSuchKey as per the docs, and also consistent with the behavior of S3.Client.get_object().

Current Behavior

The function raises S3.Client.exceptions.ClientError.

Reproduction Steps

session = boto3.Session()
client = session.client("s3")
client.head_object(Bucket="MyBucket", Key="NonExistingKey")

Possible Solution

Raise the expected error type.

Additional Information/Context

No response

SDK version used

boto3==1.28.83 and botocore==1.31.83

Environment details (OS name and version, etc.)

WSL 2 (Ubuntu 20.04)

[tim-finnigan]

Thanks for reaching out and your patience here. Related issues have come up here a few times before, for example #2499. Both the HeadObject and HeadBucket APIs return 404 errors if the object or bucket does not exist. And as noted in the documentation:

A HEAD request has the same options as a GET operation on an object. The response is identical to the GET response except that there is no response body. Because of this, if the HEAD request generates an error, it returns a generic code, such as 400 Bad Request, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 412 Precondition Failed, or 304 Not Modified. It's not possible to retrieve the exact exception of these error codes.

So this is the behavior of the underlying S3 API and therefore not something that will be addressed in Boto3. As mentioned in previous issues it would be a breaking change to update the model. But please use the Provide feedback at the bottom of API documentation pages to send any additional feedback directly to the S3 team.

[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.