Skip to the page

Using the API

Retries and idempotency

A request that timed out may or may not have happened. Here is how to find out, and what you may simply send again.

No Idempotency-Key header

The Rykloud API does not read an Idempotency-Key header. Repeat safety comes from how its operations are shaped, below. A header you send is ignored, not refused.

What happens when you send it twice

OperationA second timeSo
Any read (GET, and environments.quote)The same, or newer, answer.Retry freely.
changes.apply409 wrong_state: the change is already approved, applying or waiting for approval.Safe. Read the change to see where it is.
settings.apply409 not_previewed: already on its way or done.Safe.
environments.approve, approveUpdate409 already_approved or not_awaiting_approval.Safe.
stop, restore, retry, cancel, destroy, wake409 busy while the first is under way, or wrong_state once it is done.Safe. Follow the environment instead of asking again.
changes.preview, settings.previewA new preview; nothing is changed until one is applied.Safe; an unapplied preview lapses after an hour.
Creates: organisations, projects, environments, invitations, builds, domains, VPN keysA second one may be made.Check first: list what exists, then retry only if the first is not there.

Why a change cannot happen twice

A change is made in two calls: a preview, which only plans, and an apply, which names the preview by id and states the price the preview gave. An applied preview is no longer waiting, so a second apply is refused rather than made again, and the refusal is recorded in activity. The same holds for approvals: each names the exact plan it approves, and a plan approved once cannot be approved into a second start.

How to retry

  • Retry failures, never refusals: 5xx, 502 upstream_failed, 503 not_ready and a timeout, with growing pauses (one second, then two, four, and so on) and a limit. A 4xx answers the same however often it is sent (a refusal is not a failure).
  • 409 busy means another action came first: wait for the environment to settle (environments.get, or rykloud envs watch), then decide again.
  • 429 from the edge means you sent too much at once: slow down (Rate limits).
  • The CLI already does the right thing: exit code 8 means retrying may help, exit code 5 means it will not.