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.
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
| Code | Status | Meaning | Retry |
|---|---|---|---|
bad_request | 400 | A field failed its check; the message names the field and why. | No: change the request |
cli_too_old | 400 | A rykloud CLI older than the oldest Rykloud accepts; detail.minimum says which. Upgrade it. | No: change the request |
unauthorized | 401 | No bearer token, or one Rykloud does not know. | No: change the request |
session_ended | 401 | The session ended, was signed out or revoked, or its refresh token was used twice. Sign in again. | No: change the request |
forbidden | 403 | This caller may not use this route. | No: change the request |
scope_insufficient | 403 | A read session asked for a write; detail.needs is "write". Sign in with write scope. | No: change the request |
not_found | 404 | It 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 |
conflict | 409 | It clashes with something that exists. | No: change the request |
refused | 409 | A rule said no; the message says which. | No: change the request |
internal | 500 | Rykloud failed. Try again after a pause; if it lasts, write to support. | Yes, after a pause |
upstream_failed | 502 | A system Rykloud depends on failed. Try again after a pause. | Yes, after a pause |
signin_refused | 401 | The ID token could not be verified (wrong client, too old, or not from the Rykon account). | No: change the request |
email_unverified | 403 | The Rykon account has not confirmed its email address yet. | No: change the request |
wrong_state | 409 | It is not in a state that allows this (a change already applied, an environment already stopped). | No: change the request |
busy | 409 | Something 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_ready | 503 | Not ready yet (the catalogue, or the environment for a read). Try again shortly. | Yes, after a pause |
logs_unavailable | 502 | The logs could not be read this time. Try again shortly. | Yes, after a pause |
plan_stale | 409 | The preview is older than it stands for (an hour), or the resource changed since. Preview again. | No: change the request |
plan_changed | 409 | The plan was replaced since you read it. Read the environment again and approve the plan it shows. | No: change the request |
price_changed | 409 | The price you sent is not the preview's. Preview again and apply at the price shown. | No: change the request |
price_mismatch | 409 | The monthly price you sent is not the change's, to the cent. | No: change the request |
preview_expired | 409 | The settings preview expired. Preview again. | No: change the request |
not_previewed | 409 | This settings change is already on its way or done. | No: change the request |
change_not_found | 409 | The settings change was withdrawn or replaced. | No: change the request |
change_open | 409 | Another change to the same resource is still open. | No: change the request |
already_approved | 409 | That plan is approved already. | No: change the request |
not_awaiting_approval | 409 | Nothing is waiting for approval. | No: change the request |
no_change | 409 | The change would change nothing. | No: change the request |
no_drift | 409 | Nothing changed outside Rykloud. | No: change the request |
not_allowed | 403 | Your role in the project or environment does not allow it. | No: change the request |
not_approver | 403 | Only an owner approves this. | No: change the request |
own_change | 403 | A second person must approve a change; it cannot be its author. | No: change the request |
not_owner | 403 | Only an owner (or the billing role, for billing) may do this. | No: change the request |
not_org_admin | 403 | Only an owner or admin may do this. | No: change the request |
name_taken | 409 | Another resource in the environment has that name. | No: change the request |
protected | 409 | It is protected; turn protection off first. | No: change the request |
in_use | 409 | Something still connects to it. | No: change the request |
outside_window | 409 | Outside the time it can be done. | No: change the request |
no_backups | 409 | It has no backups to use. | No: change the request |
no_credentials | 409 | It has no connection details to reveal. | No: change the request |
no_place | 409 | Nothing on offer matches that size and place. | No: change the request |
data_location | 409 | The organisation keeps its data elsewhere. | No: change the request |
coming_soon | 409 | Not offered here. | No: change the request |
vpn_key_limit | 409 | Five live VPN keys per person per environment; revoke one first. | No: change the request |
organisation_limit | 409 | A person owns at most five organisations. | No: change the request |
limit_live | 409 | The organisation runs as many environments as it may. | No: change the request |
limit_spend | 409 | It would go past a spending limit. | No: change the request |
limit_account_budget | 409 | It would go past the cloud account's budget. | No: change the request |
prices_not_published | 409 | Rykloud has no published prices yet, so nothing billable can start. | No: change the request |
payment_required | 409 | Add a payment method or prepaid credit in Billing first. | No: change the request |
hard_limit | 409 | This month's spend reached the organisation's hard limit. | No: change the request |
suspended | 409 | The organisation is suspended. | No: change the request |
too_many_mailboxes | 400 | More mailboxes per seat than a team may have. | No: change the request |
seat_price_not_set | 409 | The AI team has no published seat price yet. | No: change the request |
resend_too_soon | 429 | Sent a moment ago; detail.retryAfterSeconds says when it may be sent again. | Yes, once the reason passes |
resend_limit | 409 | Sent 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 code | Meaning |
|---|---|
0 | done |
1 | failed (or you answered no at a prompt) |
2 | used wrongly: an unknown flag, a missing argument or confirmation |
3 | not signed in, or the session ended |
4 | not found (or not yours to see) |
5 | refused by a rule: a role, a limit, the payment gate, a protected resource |
6 | waiting for a person: an approval you cannot give |
7 | cannot reach Rykloud (network, address, timeout) |
8 | Rykloud failed or is busy; retrying may help |
10 | rykloud diff --exit-code found differences |
130 | interrupted |