Skip to main content

Conditional requests

Conditional Requests in the S3 API allow performing operations only when certain conditions are met using headers. You can use them to:

  • perform read and write requests with a preliminary check of object state;
  • manage object updates and uploads based on their current state or metadata;
  • comply with common usage scenarios according to S3 standards;
  • protect data against accidental overwriting;
  • optimize traffic costs.

Conditional requests can be used for various scenarios.

Headers

OperationSupported headers
PutObject
  • If-Match;
  • If-None-Match
CopyObject
  • x-amz-copy-source-if-match;
  • x-amz-copy-source-if-none-match;
  • x-amz-copy-source-if-modified-since;
  • x-amz-copy-source-if-unmodified-since;
  • If-Match;
  • If-None-Match
UploadPartCopy
  • x-amz-copy-source-if-match;
  • x-amz-copy-source-if-none-match;
  • x-amz-copy-source-if-modified-since;
  • x-amz-copy-source-if-unmodified-since;
  • If-Match;
  • If-None-Match
DeleteObjectIf-Match
CompleteMultipartUpload
  • If-Match;
  • If-None-Match

PutObject operations

For examples of uploading objects with conditions, see the Upload object section of the AWS CLI guide.

HeaderConditional executionError on failure
If-MatchThe object is written if an active version exists and its ETag matches the value specified in the header412 Precondition Failed
If-None-MatchThe object is written if the key has no active version, including a delete marker412 Precondition Failed

CopyObject and UploadPartCopy operations

For examples of copying objects with conditions, see the Copy object section of the AWS CLI guide.

HeaderConditional executionError on failure
x-amz-copy-source-if-matchThe object is copied if the ETag of the source object matches the value specified in the header412 Precondition Failed
x-amz-copy-source-if-none-matchThe object is copied if the ETag of the source object does not match the value specified in the header412 Precondition Failed
x-amz-copy-source-if-modified-sinceThe object is copied if the object was modified after the date specified in the header412 Precondition Failed
x-amz-copy-source-if-unmodified-sinceThe object is copied if the object has not been modified after the date specified in the header412 Precondition Failed
If-MatchThe object is copied if an active version exists and its ETag matches the value specified in the header412 Precondition Failed
If-None-MatchThe object is copied if the key has no active version, including a delete marker412 Precondition Failed

DeleteObject operations

For examples of deleting objects with conditions, see the Delete object section of the AWS CLI guide.

HeaderConditional executionError on failure
If-MatchThe object is deleted if an active version exists and its ETag matches the value specified in the header412 Precondition Failed

CompleteMultipartUpload operations

HeaderConditional executionError on failure
If-MatchCompleting a segmented upload is performed if the object ETag matches the value specified in the header412 Precondition Failed
If-None-MatchCompleting a segmented upload is performed if the object does not exist412 Precondition Failed

Error descriptions

404 Not FoundObject not found (for example, with the If-Match header)
409 ConflictThe object was modified or deleted before the conditional operation was performed
412 Precondition FailedThe condition in the header was not met

Use case examples

  • protection against update conflicts — the object will be updated only if it has not changed since the last request (the If-Match header);
  • data synchronization — the object will be downloaded only if it was modified after the specified time (the If-Modified-Since header);
  • read optimization — the object will be retrieved only if it does not match the local version (the If-None-Match header);
  • overwrite protection — the object will not be written to the key if another object with that key already exists (the If-None-Match header).