Errors

Quota

409, plain text. Creating, cloning, restoring or taking a snapshot past a ceiling, or starting a workspace while over the disk ceiling:

{dimension}: {used} of {limit} in use; request more under Quota

{dimension} is workspaces, environments, snapshots, diskGb, cpu, memoryGb or sandboxes. A retry after you free something succeeds. To raise a ceiling, open a quota request; it answers 409 a request is already pending while another of the same kind is open.

Team access

The team routes have their own wording; see teams, keys and tokens.

Names

422, JSON. A workspace, environment or session name that breaks the rule:

{"error": "name must be 1-40 lowercase letters, digits or '-', start with a letter, end with a letter or digit, no '--', and not be reserved (ws, env, api, admin, system, kl, bld-*) or look like an id"}

400, plain text. A service name that breaks its rule (reserved words are allowed for services): service name "{name}" must be 1-40 lowercase letters, digits or '-', start with a letter, end with a letter or digit, no '--'.

409, plain text. The name is taken by another of yours:

• a workspace named "{name}" already exists here
• an environment named "{name}" already exists here
• you already have a session named {name} in {team}

409, JSON. The name given matches more than one object you can see. Qualify it as team/name (or ?owner=), or use the id:

{"error": "\"backend\" is ambiguous; qualify it as owner/name", "matches": [{"id": "ws-…", "name": "backend", "team": "acme"}]}

A session named ambiguously across teams answers more than one session is named {name}; name it as team/{name} as plain text (api/sessions.rs:273).

Lifecycle conflicts

All 409, plain text unless noted.

Sandbox routes answer 409 and 422 in JSON (api/sandboxes/mod.rs:97-103); their wording is on the sandbox reference.

Named volumes

Plain text unless noted. The first four rows are the answers of a push. The sandbox routes answer in JSON.

A pipeline job that saves a volume ends with one of these sentences as its detail:

Out-of-range values

422. A value outside its bounds (ttl_secs, sandbox timeout_secs, cpu, memory_gb) or a package pin that cannot be resolved. The body names the field and the range, for example ttl_secs must be 600..=2592000 seconds. See limits.

Pipelines

Plain text. A refusal of a definition or a start lists every problem at once, one line each, after its first line.

The cause and the fix of each sentence are in the troubleshooting tables of Pipelines.

Git credentials

Plain text. The git credential helper writes the sentence to the log of the step as kl git-credential: {sentence}, and git then fails the command.

The cause and the fix of each sentence are in the troubleshooting table of Code in a job.