---
title: "Idempotency and safe retries"
url: https://docs.corefinity.com/api/idempotency
type: page
last_updated: 2026-11-13
feature: api
---
# Idempotency and safe retries

Which requests take an idempotency key, and the checks that make every other retry safe.

Four requests read an `Idempotency-Key` header. Everywhere else, sending the same change twice is guarded by the checks below.

## Requests that read `Idempotency-Key`

Send a UUID of your choosing. The same key sent again answers the first request's outcome with `replayed: true` and does nothing twice.

A key that belongs to a different request is refused `409` `conflict`, and a header that is not a UUID is refused `422`.

| Request                                                              | What it does               |
| -------------------------------------------------------------------- | -------------------------- |
| `POST /environments/{environment}/deployments/{deployment}/cancel`   | Cancel a deployment        |
| `POST /environments/{environment}/deployments/{deployment}/retry`    | Retry a deployment         |
| `POST /environments/{environment}/deployments/{deployment}/rollback` | Roll back to a deployment  |
| `POST /environments/{environment}/deployments/{deployment}/run`      | Start a waiting deployment |

## Safe to repeat

| Request                                                                                                                   | Why                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| A `GET`                                                                                                                   | Reads change nothing, unless the endpoint's reference page says its answer is given once |
| A `POST` that only validates or previews what it is sent, such as checking a schedule, rules or a file before saving them | It saves nothing, sends nothing and starts no work                                       |
| A `PUT` of a whole set with its `version`                                                                                 | The second copy is refused `stale` or answers `"operation": null`                        |

A request named test, verify or check is not always one of these: one that sends a message, runs something on the site or starts a test does so again each time it is accepted, and counts against its limit again. Treat it as a request that starts work, and read its outcome first: see [After a timeout](#after-a-timeout).

`POST /corestack/sites/{site}/email/test` sends another test email each time it is accepted, and each one counts towards the 20 tests a site may send a day.

## Versioned saves

Saves that replace what was read carry a `version`. Read the resource, change it, and send it back with the `version` you read.

| Save                                                                         | What it does                               |
| ---------------------------------------------------------------------------- | ------------------------------------------ |
| `PUT /corestack/billing/account/vat-number`                                  | Update the VAT number                      |
| `PUT /corestack/sites/{site}/crons`                                          | Replace a site's scheduled tasks           |
| `POST /corestack/companies/{company}/deploy-templates/{platform}/restore`    | Restore a version of a deployment template |
| `POST /corestack/sites/{site}/deployments/pipeline/{binding}/template-reset` | Reset a pipeline's stages to its template  |
| `PUT /corestack/sites/{site}/domains`                                        | Replace a site's extra domains             |
| `PUT /corestack/sites/{site}/error-pages`                                    | Replace a site's error pages               |
| `POST /corestack/sites/{site}/error-pages/copy`                              | Copy error pages to another environment    |
| `POST /corestack/sites/{site}/error-pages/reset`                             | Reset error pages to the defaults          |
| `POST /corestack/sites/{site}/error-pages/retry`                             | Retry applying the error pages             |
| `POST /corestack/sites/{site}/error-pages/revert`                            | Restore an error page revision             |
| `PUT /corestack/sites/{site}/http-auth`                                      | Replace a site's HTTP authentication       |
| `PUT /corestack/sites/{site}/nginx-rules`                                    | Replace a site's Nginx rules               |
| `POST /corestack/sites/{site}/nginx-rules/copy`                              | Copy Nginx rules between environments      |
| `POST /corestack/sites/{site}/nginx-rules/corefinity-rules/move`             | Move Corefinity's rules into yours         |
| `POST /corestack/sites/{site}/nginx-rules/drift`                             | Answer a change made outside               |
| `POST /corestack/sites/{site}/nginx-rules/revisions/{revision}/revert`       | Restore an Nginx revision                  |
| `PUT /corestack/sites/{site}/php-runtime`                                    | Update a site's PHP configuration          |
| `POST /corestack/sites/{site}/php-runtime/revert`                            | Restore a PHP configuration revision       |
| `PUT /corestack/sites/{site}/php-settings`                                   | Update memory, upload and execution limits |
| `PUT /corestack/sites/{site}/redirects`                                      | Replace a site's redirects                 |
| `POST /corestack/sites/{site}/varnish`                                       | Update a site's Varnish switch by POST     |
| `PUT /corestack/sites/{site}/varnish`                                        | Update a site's Varnish switch             |
| `PUT /corestack/sites/{site}/varnish/version`                                | Update a site's Varnish version            |
| `PUT /corestack/sites/{site}/varnish/vcl`                                    | Replace a site's custom VCL                |

| Answer                         | Meaning                             | What to do                                        |
| ------------------------------ | ----------------------------------- | ------------------------------------------------- |
| `201` with an operation        | Saved; the change is applying       | Follow the [operation](/api/long-running-work)    |
| `200` with `"operation": null` | Nothing differed from what is saved | Nothing                                           |
| `409` `stale`                  | The set changed since you read it   | Read it again, reapply your change, send it again |

## One change at a time

While a change to a site is running, another change to the same site is refused `409` `busy`. Wait for the running operation to finish before sending the next.

## After a timeout

If a request that starts work times out, do not send it again blind.

1. **Read first**

   Read the resource, or list the site's operations with `GET /corestack/sites/{site}/operations`.

2. **Decide**

   If the change is there or an operation is running, follow it. If not, send the request again.

> **Warning:** Requests that create something new each time, such as taking a snapshot, are not guarded. A blind retry can create a second one.
