Skip to the page

Using the API

Errors and references

One shape for every error, a code your program can branch on, and a sentence a person can read.

The error body

Any answer that is not a success is JSON with error (a stable code in snake_case), message (what happened, in words meant for a person; it may change) and sometimes detail, an object with what to do next, like minimum for cli_too_old or retryAfterSeconds for resend_too_soon. Branch on error, show message.

A refusal
HTTP/2 409
content-type: application/json; charset=utf-8

{
  "error": "price_changed",
  "message": "the price is $14.00 a month, not $12.50; look at it again"
}

A field that fails its check is 400 bad_request with each problem as field: reason in the message. A body over 64 KB is refused before it is read.

A refusal is not a failure

Rykloud draws one line through its errors. A refusal (every 4xx) means a rule said no: a role, a price that changed, a limit, a state. Sending the same request again gives the same answer, so do not retry it; change the request or ask a person. A failure (5xx) means something broke and a later try may pass. Retries and idempotency says how to retry safely.

Codes

CodeStatusMeaningRetry
bad_request400A field failed its check; the message names the field and why.No: change the request
cli_too_old400A rykloud CLI older than the oldest Rykloud accepts; detail.minimum says which. Upgrade it.No: change the request
unauthorized401No bearer token, or one Rykloud does not know.No: change the request
session_ended401The session ended, was signed out or revoked, or its refresh token was used twice. Sign in again.No: change the request
forbidden403This caller may not use this route.No: change the request
scope_insufficient403A read session asked for a write; detail.needs is "write". Sign in with write scope.No: change the request
not_found404It does not exist, or it is not yours to see (an organisation you are not in answers 404, never 403). Also any route outside the public API.No: change the request
conflict409It clashes with something that exists.No: change the request
refused409A rule said no; the message says which.No: change the request
internal500Rykloud failed. Try again after a pause; if it lasts, write to support.Yes, after a pause
upstream_failed502A system Rykloud depends on failed. Try again after a pause.Yes, after a pause
signin_refused401The ID token could not be verified (wrong client, too old, or not from the Rykon account).No: change the request
email_unverified403The Rykon account has not confirmed its email address yet.No: change the request
wrong_state409It is not in a state that allows this (a change already applied, an environment already stopped).No: change the request
busy409Something else was asked of it first; wait for that to finish, then ask again. Reading logs answers 503 busy for the same reason.Yes, once the reason passes
not_ready503Not ready yet (the catalogue, or the environment for a read). Try again shortly.Yes, after a pause
logs_unavailable502The logs could not be read this time. Try again shortly.Yes, after a pause
plan_stale409The preview is older than it stands for (an hour), or the resource changed since. Preview again.No: change the request
plan_changed409The plan was replaced since you read it. Read the environment again and approve the plan it shows.No: change the request
price_changed409The price you sent is not the preview's. Preview again and apply at the price shown.No: change the request
price_mismatch409The monthly price you sent is not the change's, to the cent.No: change the request
preview_expired409The settings preview expired. Preview again.No: change the request
not_previewed409This settings change is already on its way or done.No: change the request
change_not_found409The settings change was withdrawn or replaced.No: change the request
change_open409Another change to the same resource is still open.No: change the request
already_approved409That plan is approved already.No: change the request
not_awaiting_approval409Nothing is waiting for approval.No: change the request
no_change409The change would change nothing.No: change the request
no_drift409Nothing changed outside Rykloud.No: change the request
not_allowed403Your role in the project or environment does not allow it.No: change the request
not_approver403Only an owner approves this.No: change the request
own_change403A second person must approve a change; it cannot be its author.No: change the request
not_owner403Only an owner (or the billing role, for billing) may do this.No: change the request
not_org_admin403Only an owner or admin may do this.No: change the request
name_taken409Another resource in the environment has that name.No: change the request
protected409It is protected; turn protection off first.No: change the request
in_use409Something still connects to it.No: change the request
outside_window409Outside the time it can be done.No: change the request
no_backups409It has no backups to use.No: change the request
no_credentials409It has no connection details to reveal.No: change the request
no_place409Nothing on offer matches that size and place.No: change the request
data_location409The organisation keeps its data elsewhere.No: change the request
coming_soon409Not offered here.No: change the request
vpn_key_limit409Five live VPN keys per person per environment; revoke one first.No: change the request
organisation_limit409A person owns at most five organisations.No: change the request
limit_live409The organisation runs as many environments as it may.No: change the request
limit_spend409It would go past a spending limit.No: change the request
limit_account_budget409It would go past the cloud account's budget.No: change the request
prices_not_published409Rykloud has no published prices yet, so nothing billable can start.No: change the request
payment_required409Add a payment method or prepaid credit in Billing first.No: change the request
hard_limit409This month's spend reached the organisation's hard limit.No: change the request
suspended409The organisation is suspended.No: change the request
too_many_mailboxes400More mailboxes per seat than a team may have.No: change the request
seat_price_not_set409The AI team has no published seat price yet.No: change the request
resend_too_soon429Sent a moment ago; detail.retryAfterSeconds says when it may be sent again.Yes, once the reason passes
resend_limit409Sent ten times already.No: change the request

Each operation's page lists the codes that route itself answers. New codes may be added; treat one you do not know by its status.

The req_ reference

Everything Rykloud does for you carries a reference like req_3f9c0d2e7a4b4c1f9e8d7c6b5a4f3e2d: req_ and 32 hexadecimal characters. It names the operation in Rykloud's own records, so support can find exactly what happened.

  • Each event in activity has a requestId.
  • An environment's operations (environments.get) each have a requestId, beside their phases.
  • Builds and updates carry a reference, and a failed step's message ends with it: Reference req_....

The error body of a refused request has no reference; the refusal is recorded in activity, where it has one. Quote the reference when you write to support@rykloud.com.

Exit codes in the CLI

The rykloud CLI turns these codes into exit codes that stay the same within a major version. With -o json, an error is one JSON line on standard error: {"error":{"code":"refused","message":"...","exitCode":5}}.

Exit codeMeaning
0done
1failed (or you answered no at a prompt)
2used wrongly: an unknown flag, a missing argument or confirmation
3not signed in, or the session ended
4not found (or not yours to see)
5refused by a rule: a role, a limit, the payment gate, a protected resource
6waiting for a person: an approval you cannot give
7cannot reach Rykloud (network, address, timeout)
8Rykloud failed or is busy; retrying may help
10rykloud diff --exit-code found differences
130interrupted