Error catalog

Every error of the API is a JSON object with a sentence and a stable code: { "error": "name already taken", "code": "name-taken" }. Branch on code, show error. A code your program does not know should fall back on the HTTP status; the generic code of a status is listed first. See REST API basics for the request and response format.

Generic codes

One per HTTP status. A route answers one of these when it has nothing more specific to say.

Status	Code	Meaning
400	bad-request	The request is malformed or a field is out of range. error names every field; issues lists them.
401	unauthenticated	No API key, or one that does not work (unknown, revoked or expired).
403	forbidden	The key may not do this.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.
409	conflict	The request conflicts with the current state.
410	gone	The object existed and is gone.
413	too-large	The body is larger than the route accepts.
422	unprocessable	The request is well-formed but cannot be carried out as it is.
426	upgrade-required	The route needs a WebSocket upgrade; use the CLI.
429	rate-limited	Too many requests; wait for Retry-After and try again.
500	internal	Something failed on Rytiv’s side. The sentence carries a reference you can quote.
501	not-implemented	Not available on this installation.
502	upstream-failed	A host, the object store or a connected service failed.
503	unavailable	Not possible right now; try again shortly.
504	upstream-timeout	A host or a connected service did not answer in time.

Codes shared by several routes

Status	Code	Meaning
409	name-taken	The name is used somewhere on Rytiv (an app, a database, a volume or a bucket).
409	already-exists	You already have it; an idempotent create may treat this as done.
400	name-reserved	The platform keeps this name (for example api, console, docs, www, and every name that is rytiv or starts with rytiv-).
403	org-suspended	The organization was suspended by the operator.
403	delegation-refused	X-Rytiv-Org names an organization this key may not act for.
403	creator-proof	Creating an organization needs the console’s signed proof of the person.
403	token-scope	The key’s scopes do not cover this route, this mail domain or this upgrade. The sentence names the scope needed.
503	no-capacity	No host in the region has room for the machine right now; try again.
503	lease-held	Another host still holds the volume or checkpoint; try again shortly.
503	create-failed	The host could not create the machine (image, start command or port). The sentence says which.
503	database-unavailable	The platform database cannot be reached right now; retry after Retry-After.
408	wait-timeout	The wait ran out before the machine reached the state; ask again.
409	not-a-copy	The database is neither a fork nor a branch; its URL came with its create answer.
409	not-ready	The copy is still restoring, or failed; there is nothing to hand out yet.
409	url-handed-out	The URL of this copy was handed out already. It leaves the platform exactly once.
403	agent-token-production-readonly	An agent token of class production may read; a change needs a person.
403	agent-token-production-data	An agent token of class production without prodDataRead may not read what production holds.
403	agent-token-credential	No agent token mints, reveals or revokes a credential, or administers the organization.
403	agent-token-app-scope	The request is about an app outside the token’s list, or about no app at all.
403	agent-token-route-unknown	A route the agent rules do not know is refused.
403	agent-token-delegation	An agent token acts in its own organization only.
503	agent-audit-unavailable	The audit record of the action could not be written, so the action did not run; ask again shortly.
403	org-limit-computers	The organization has as many computers as it may have. The body carries limit and current. Delete one, or contact us for more.
403	org-limit-apps	The organization has as many apps as it may have (computers included). The body carries limit and current.

Machine actions

Answered by POST /v1/machines/:id/:action and a machine create when the host could not start the machine.

Status	Code	Meaning
503	start-interrupted	The start was interrupted on the host.
503	guest-exited	The machine’s process ended during the start.
503	port-timeout	The machine did not answer on its port in time.
503	no-capacity	No host in the region has room for the machine right now; try again.
503	host-refused	The host refused the action.
503	host-unreachable	The host did not answer.
409	machine-busy	Another operation on the machine is in progress; try again.
503	create-failed	The host could not create the machine (image, start command or port). The sentence says which.

Rollbacks

Answered by POST /v1/apps/:name/rollback.

Status	Code	Meaning
404	release-not-found	No release with that version or id.
409	rollback-target-current	That release is the one that runs.
409	rollback-same-build	That release runs the same build as the current one.
409	rollback-target-never-live	That release never went live, so there is nothing to bring back.
409	release-artifact-gone	The release’s image is no longer available.
409	no-previous-release	There is no earlier release that went live.
409	rollback-not-for-resources	The app backs a database; databases are restored, not rolled back.
409	rollback-needs-machine-config	The app has no machine whose settings a rollback could reuse.
409	deploy-in-flight	Another deploy of this app is running.

Credit and billing

Answered by the routes under /v1/billing.

Status	Code	Meaning
402	credit-blocked	The organization’s credit is at zero: nothing new starts until a top-up. Reads, stops and the billing routes still answer.
409	no-customer	No payment relationship yet; a first top-up creates it.
403	billing-console-only	A billing change is made in the console by an admin, not with an API key.
409	not-prepaid	The organization has no credit account; only org creation or an operator’s grant starts prepaid credit.

Computers

Answered by the viewer and control routes of a computer.

Status	Code	Meaning
409	not-a-computer	The machine is not a computer (it has no COMPUTER_VIEW_KEY), or it is a console or job machine.
409	machine-stopped	The machine is stopped; start it first.
503	not-placed	The machine has no host yet.
503	view-key-unreadable	The computer’s key cannot be decrypted right now.
409	view-key-too-short	The computer’s key is too short; the image would refuse to start with it.
409	several-machines	Control needs exactly one machine; the app has several.
409	control-held	Somebody else holds control; the body names heldBy, until and leaseId. Use force to take it.
409	control-busy	Another change of control is in progress; try again after Retry-After.
409	computer-control-missing	The machine runs a computer image from before control leases; deploy it again.
409	guest-agent-absent	The machine has no guest channel; it was created before shell sessions existed. Deploy it again.
503	guest-channel-off	The guest channel is switched off on the machine’s host.
503	guest-unreachable	The guest did not answer; try again after Retry-After.
502	guest-failed	The control tool in the machine ran and failed.
409	managed-service	A managed database; its machine is not opened to a shell.
503	resource-check-failed	Could not tell whether the machine backs a managed database; try again.

Shell sessions

Answered when a shell, a tunnel or a file transfer into a machine is refused (ry exec, ry ssh, ry proxy).

Status	Code	Meaning
404	machine-not-found	No such machine in your organization.
409	console-machine	The machine is a console or job machine; it takes no shell.
409	managed-service	A managed database; its machine is not opened to a shell.
503	resource-check-failed	Could not tell whether the machine backs a managed database; try again.
409	machine-stopped	The machine is stopped; start it first.
409	machine-suspended-no-wake	The machine is suspended and cannot be woken for this.
503	machine-not-placed	The machine has no host yet.
429	too-many-sessions	The machine has as many shell sessions open as it may.
503	host-unavailable	The machine’s host is not reachable right now.
503	audit-unavailable	The audit record of the session could not be written, so it was not opened.
503	exec-disabled	Shell sessions are switched off on this installation.
409	guest-agent-absent	The machine has no guest channel; it was created before shell sessions existed. Deploy it again.
504	guest-agent-timeout	The guest did not answer in time.
409	guest-agent-version	The guest’s agent is too old for this; deploy the machine again.
502	guest-agent-protocol	The guest answered something the platform did not expect.
502	host-error	The host failed to open the session.
504	host-timeout	The host did not answer in time.

Validation errors

A request that breaks a schema answers 400 with the code bad-request. The error sentence names every field that was wrong (invalid request: memoryMb: Too big: expected number to be <=16384), and issues carries the same problems as a list, one entry per field, each with path and message. Fix every named field at once; the server reports them all in one answer.