---
title: "Conditional requests"
sidebar_label: "Conditional requests"
description: "What conditional requests are for and which headers can be used"
sidebar_position: 6
---

import Formbricks from '@theme/MDXComponents/Formbricks'
import {CustomTable} from '@selectel/docux/components'

# Conditional requests

Conditional requests in the [S3 API](/api/object-storage-s3/) allow you to perform operations only when certain conditions are met using [headers](#headers). They allow you 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](#usage-examples).

## Headers \{#headers}

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Operation</th><th>Supported headers</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>[PutObject](#put-object)</td>

        <td>
          * `If-Match;`
          * `If-None-Match`
        </td>
      </tr>

      <tr>
        <td>[CopyObject](#copy-object-and-upload-part-copy)</td>

        <td>
          * `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`
        </td>
      </tr>

      <tr>
        <td>[UploadPartCopy](#copy-object-and-upload-part-copy)</td>

        <td>
          * `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`
        </td>
      </tr>

      <tr>
        <td>[DeleteObject](#delete-object)</td><td>`If-Match`</td>
      </tr>

      <tr>
        <td>[CompleteMultipartUpload](#complete-multipart-upload)</td>

        <td>
          * `If-Match;`
          * `If-None-Match`
        </td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### PutObject operations \{#put-object}

Examples of uploading objects with conditions can be found in the [Upload object](/s3/tools/aws-cli.mdx#upload-object) subsection of the [AWS CLI](/s3/tools/aws-cli.mdx) manual.

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Conditional execution</th><th>Error on failure</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <th>`If-Match`</th><td>The object is written if an active version exists and its ETag matches the value specified in the header</td><td>`412 Precondition Failed`</td>
      </tr>

      <tr>
        <th>`If-None-Match`</th><td>The object is written if the key has no active version, including a delete marker</td><td>`412 Precondition Failed`</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### CopyObject and UploadPartCopy operations \{#copy-object-and-upload-part-copy}

Examples of copying objects with conditions can be found in the [Copy object](/s3/tools/aws-cli.mdx#copy-object) subsection of the [AWS CLI](/s3/tools/aws-cli.mdx) manual.

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Conditional execution</th><th>Error on failure</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <th>`x-amz-copy-source-if-match`</th><td>The object is copied if the ETag of the source object matches the value specified in the header</td><td>`412 Precondition Failed`</td>
      </tr>

      <tr>
        <th>`x-amz-copy-source-if-none-match`</th><td>The object is copied if the ETag of the source object does not match the value specified in the header</td><td>`412 Precondition Failed`</td>
      </tr>

      <tr>
        <th>`x-amz-copy-source-if-modified-since`</th><td>The object is copied if the object was modified after the date specified in the header</td><td>`412 Precondition Failed`</td>
      </tr>

      <tr>
        <th>`x-amz-copy-source-if-unmodified-since`</th><td>The object is copied if the object has not been modified after the date specified in the header</td><td>`412 Precondition Failed`</td>
      </tr>

      <tr>
        <th>`If-Match`</th><td>The object is copied if an active version exists and its ETag matches the value specified in the header</td><td>`412 Precondition Failed`</td>
      </tr>

      <tr>
        <th>`If-None-Match`</th><td>The object is copied if the key has no active version, including a delete marker</td><td>`412 Precondition Failed`</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### DeleteObject operations \{#delete-object}

Examples of deleting objects with conditions can be found in the [Delete object](/s3/tools/aws-cli.mdx#delete-object) subsection of the [AWS CLI](/s3/tools/aws-cli.mdx) manual.

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Conditional execution</th><th>Error on failure</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <th>`If-Match`</th><td>The object is deleted if an active version exists and its ETag matches the value specified in the header</td><td>`412 Precondition Failed`</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### CompleteMultipartUpload operations \{#complete-multipart-upload}

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Conditional execution</th><th>Error on failure</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <th>`If-Match`</th><td>Completion of the [segmented upload](/s3/objects/upload-object.mdx#segmented-upload) is performed if the object ETag matches the value specified in the header</td><td>`412 Precondition Failed`</td>
      </tr>

      <tr>
        <th>`If-None-Match`</th><td>Completion of the [segmented upload](/s3/objects/upload-object.mdx#segmented-upload) is performed if the object does not exist</td><td>`412 Precondition Failed`</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

## Error descriptions \{#errors}

<CustomTable>
  <table>
    <tbody>
      <tr>
        <th>`404 Not Found`</th><td>Object not found (for example, when using the `If-Match` header)</td>
      </tr>

      <tr>
        <th>`409 Conflict`</th><td>The object was modified or deleted before the conditional operation was performed</td>
      </tr>

      <tr>
        <th>`412 Precondition Failed`</th><td>The condition in the header was not met</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

## Use case examples \{#usage-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).

<Formbricks />