Error codes

Every error answer carries a code. Some also carry a lower-case error key, which exists so a client can branch on the case without matching on prose:

{
  "code": "TRIAL_CREDITS_EXHAUSTED",
  "error": "trial_credits_exhausted",
  "message": "Your trial credits are used up. Connect a runner to keep your AI team working."
}

code and error are stable. message is written for a person and may be reworded, so never match on it.

Access and identity

Code	HTTP	Means	Do
UNAUTHORIZED	401	No valid session	Sign in again
FORBIDDEN	403	Signed in, missing a permission. The message names the key	Have an admin tick that permission
TENANCY	403	The record belongs to another workspace	Check the id. Workspaces never share data
TENANT_SUSPENDED	403	The workspace is suspended, so new tasks and runs are refused. Work already running finishes	Get in touch
TENANT_OFFBOARDED	403	The workspace has been closed. Its data was deleted and it cannot be reopened, so nothing new is accepted	Get in touch if you did not expect this

Requests

Code	HTTP	Means	Do
VALIDATION	400	The request body is wrong. Field errors come back in errors[]	Fix the named fields
NOT_FOUND	404	No such record	Check the id
CONFLICT	409	The record changed under you, or the change collides. Details in conflicts[]	Re-read and retry
DUPLICATE_EXPERIMENT	409	The hypothesis matches an experiment already proposed or running in the same project. The existing one comes back in existingExperimentId	Open that experiment instead of starting a second one
DUPLICATE_SUGGESTION	409	The same policy suggestion is already live for this workspace. The daily sweep raises a finding once, not once a day	Decide the one already in the queue
APPROVAL_REQUIRED	428	The action needs an approval that has not been given	Decide it in the approvals queue
NOT_IMPLEMENTED	501	The capability is not wired in this install. Knowledge search without pgvector and an embeddings key answers this	Turn the capability on, or stop calling it. It never fakes an empty result
INTERNAL	500	Something failed that was not anticipated. No details are returned	Retry, then report it

Trial credits

Code	HTTP	Branch key	Means
TRIAL_CREDITS_EXHAUSTED	402	trial_credits_exhausted	The trial grant is spent

Raised before the model call, so an exhausted workspace spends nothing. Recover by pairing a runner or connecting your own AI credential. Workspaces without a trial ledger are never metered and never see this.

Execution

Code	HTTP	Branch key	Means	Do
PLAN_CEILING	402		The task’s verification profile is above what this workspace’s plan allows on a managed run. No run is created and nothing is spent	Raise the plan, or run the task on your own runner
NO_RUNNER_AVAILABLE	503	no_runner_available	No live runner advertises the agent the work needs	Start a runner, or switch the AI runtime to Direct LLM
NO_RUNTIME_AVAILABLE	503		Every target in the agent’s runtime chain was tried and skipped. The message lists each one and why	Fix one of the listed reasons
RUNNER_RUN_FAILED	503	runner_run_failed	A run started and produced nothing usable	Read the attempt on the Execution tab
RUNNER_DEREGISTERED	410		The runner acting has been revoked. Deregistration is permanent	Pair the machine again

There is no silent fallback

When the runtime a run needs is unavailable, the request fails and says so. It never quietly runs somewhere else, on another model, or with a different agent.

Credentials and environments

Most of these are the one-time release working as designed. A runner fetches once when it prepares an attempt; a second fetch for the same attempt is refused.

Code	HTTP	Branch key	Means
NO_AGENT_CREDENTIAL	409	no_agent_credential	The run’s coding agent has nothing to sign in with. See below for what to do
AGENT_CREDENTIAL_ALREADY_RELEASED	409	agent_credential_already_released	The credential for this attempt was already handed out
NO_RUN_ENV	409	no_run_env	The run’s project environment could not be fully resolved. It fails rather than starting half configured
RUN_ENV_ALREADY_RELEASED	409	run_env_already_released	The environment for this attempt was already handed out
AGENT_CREDENTIAL_UNREFRESHABLE	401		The login uploaded for managed runs could not be renewed, usually because it was revoked. Upload it again: open the runner with commandchain-runner and press c, or run commandchain-runner creds push
NO_MCP_CREDENTIAL	409	no_mcp_credential	A secret an MCP server registration points at could not be resolved. The attempt fails rather than running with a partial tool set
MCP_CREDS_ALREADY_RELEASED	409	mcp_creds_already_released	The MCP material for this attempt was already handed out. Refreshing an OAuth token stays available
NO_MCP_SERVERS	404	no_mcp_servers	The run carries no MCP servers, so there is nothing to release

A retry gets a fresh attempt, and each attempt gets its own single release, so “already released” never blocks a retry.

no_agent_credential

It means one of two things, depending on where the run was going to happen:

• On a runner on your own machine, the runner is not signed in to the coding agent the run needs, or its sign-in expired and could not be renewed. Open the runner on that machine with commandchain-runner and follow its prompt, or run commandchain-runner signin --agent claude-code (or codex, gemini). See sign-in only or full setup.
• On CommandChain’s managed servers, no login is uploaded for managed runs. On a machine where you are signed in to that agent, open the runner with commandchain-runner and press c, or run commandchain-runner creds push. See managed runner credentials.

Repositories

Code	HTTP	Branch key	Means	Do
REPO_CREATION_NEEDS_ORG	422	repo_creation_needs_org	Creating a repository was asked for on a workspace whose GitHub App is installed on a personal account. GitHub offers no way for an app to create one there	Create it on GitHub and link it, or install the App on an organization

A name already attached to the project comes back as CONFLICT naming the repository, and creates nothing: link the existing one instead.

Live app sharing

Code	HTTP	Means
TUNNEL_UNAVAILABLE	503	This install has no transport for sharing a live app
TUNNEL_SESSION_LIMIT	409	The huddle already holds the maximum number of live sessions. See limits

Next steps

• Common issues: the same failures, indexed by symptom rather than by code.
• Limits: the ceilings behind the 402 and the 409.
• Permissions: the key a 403 names.