Idempotency and safe retries
Which requests take an idempotency key, and the checks that make every other retry safe.
On this page
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 / | Cancel a deployment |
POST / | Retry a deployment |
POST / | Roll back to a deployment |
POST / | 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.
POST / 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 / | Update the VAT number |
PUT /corestack/sites/{site}/crons | Replace a site's scheduled tasks |
POST / | Restore a version of a deployment template |
POST / | Reset a pipeline's stages to its template |
PUT /corestack/sites/{site}/domains | Replace a site's extra domains |
PUT / | Replace a site's error pages |
POST / | Copy error pages to another environment |
POST / | Reset error pages to the defaults |
POST / | Retry applying the error pages |
POST / | Restore an error page revision |
PUT / | Replace a site's HTTP authentication |
PUT / | Replace a site's Nginx rules |
POST / | Copy Nginx rules between environments |
POST / | Move Corefinity's rules into yours |
POST / | Answer a change made outside |
POST / | Restore an Nginx revision |
PUT / | Update a site's PHP configuration |
POST / | Restore a PHP configuration revision |
PUT / | Update memory, upload and execution limits |
PUT / | 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 / | Update a site's Varnish version |
PUT / | Replace a site's custom VCL |
| Answer | Meaning | What to do |
|---|---|---|
201 with an operation | Saved; the change is applying | Follow the operation |
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.
Read first
Read the resource, or list the site's operations with
GET /.corestack/ sites/ {site}/ operations Decide
If the change is there or an operation is running, follow it. If not, send the request again.
Requests that create something new each time, such as taking a snapshot, are not guarded. A blind retry can create a second one.