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
| Operation | A second time | So |
|---|---|---|
| Any read (GET, and environments.quote) | The same, or newer, answer. | Retry freely. |
| changes.apply | 409 wrong_state: the change is already approved, applying or waiting for approval. | Safe. Read the change to see where it is. |
| settings.apply | 409 not_previewed: already on its way or done. | Safe. |
| environments.approve, approveUpdate | 409 already_approved or not_awaiting_approval. | Safe. |
| stop, restore, retry, cancel, destroy, wake | 409 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.preview | A 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 keys | A 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_readyand a timeout, with growing pauses (one second, then two, four, and so on) and a limit. A4xxanswers the same however often it is sent (a refusal is not a failure). 409 busymeans another action came first: wait for the environment to settle (environments.get, orrykloud envs watch), then decide again.429from 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.