Skip to main content

Conditional requests

Last update:

Conditional requests in the S3 API allow you to perform operations only when certain conditions are met using headers. They can be used 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 different 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

Examples of uploading objects with conditions can be found in the Upload object subsection of the AWS CLI manual.

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

Examples of copying objects with conditions can be found in the Copy object subsection of the AWS CLI manual.

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

Examples of deleting objects with conditions can be found in the Delete object subsection of the AWS CLI manual.

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-MatchCompletion of the segmented upload is performed if the object ETag matches the value specified in the header412 Precondition Failed
If-None-MatchCompletion of the segmented upload is performed if the object does not exist412 Precondition Failed

Error descriptions

404 Not FoundObject not found (for example, when using 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

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