CorefinityCorefinityDocs
Open the Control PanelControl Panel
Essentials · 11 of 12

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.

RequestWhat it does
POST /environments/{environment}/deployments/{deployment}/cancelCancel a deployment
POST /environments/{environment}/deployments/{deployment}/retryRetry a deployment
POST /environments/{environment}/deployments/{deployment}/rollbackRoll back to a deployment
POST /environments/{environment}/deployments/{deployment}/runStart a waiting deployment

Safe to repeat

RequestWhy
A GETReads 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 themIt saves nothing, sends nothing and starts no work
A PUT of a whole set with its versionThe 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 /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.

SaveWhat it does
PUT /corestack/billing/account/vat-numberUpdate the VAT number
PUT /corestack/sites/{site}/cronsReplace a site's scheduled tasks
POST /corestack/companies/{company}/deploy-templates/{platform}/restoreRestore a version of a deployment template
POST /corestack/sites/{site}/deployments/pipeline/{binding}/template-resetReset a pipeline's stages to its template
PUT /corestack/sites/{site}/domainsReplace a site's extra domains
PUT /corestack/sites/{site}/error-pagesReplace a site's error pages
POST /corestack/sites/{site}/error-pages/copyCopy error pages to another environment
POST /corestack/sites/{site}/error-pages/resetReset error pages to the defaults
POST /corestack/sites/{site}/error-pages/retryRetry applying the error pages
POST /corestack/sites/{site}/error-pages/revertRestore an error page revision
PUT /corestack/sites/{site}/http-authReplace a site's HTTP authentication
PUT /corestack/sites/{site}/nginx-rulesReplace a site's Nginx rules
POST /corestack/sites/{site}/nginx-rules/copyCopy Nginx rules between environments
POST /corestack/sites/{site}/nginx-rules/corefinity-rules/moveMove Corefinity's rules into yours
POST /corestack/sites/{site}/nginx-rules/driftAnswer a change made outside
POST /corestack/sites/{site}/nginx-rules/revisions/{revision}/revertRestore an Nginx revision
PUT /corestack/sites/{site}/php-runtimeUpdate a site's PHP configuration
POST /corestack/sites/{site}/php-runtime/revertRestore a PHP configuration revision
PUT /corestack/sites/{site}/php-settingsUpdate memory, upload and execution limits
PUT /corestack/sites/{site}/redirectsReplace a site's redirects
POST /corestack/sites/{site}/varnishUpdate a site's Varnish switch by POST
PUT /corestack/sites/{site}/varnishUpdate a site's Varnish switch
PUT /corestack/sites/{site}/varnish/versionUpdate a site's Varnish version
PUT /corestack/sites/{site}/varnish/vclReplace a site's custom VCL
AnswerMeaningWhat to do
201 with an operationSaved; the change is applyingFollow the operation
200 with "operation": nullNothing differed from what is savedNothing
409 staleThe set changed since you read itRead 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.

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

Was this helpful?
Open in ClaudeOpen in ChatGPT