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

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
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
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

These four 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	There is no coding-agent credential to release for this run
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		A stored credential could not be refreshed, usually because it was revoked

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

Live app sharing

Code	HTTP	Means
TUNNEL_UNAVAILABLE	503	This install has no transport for sharing a live app
TUNNEL_SESSION_LIMIT	409	The meeting 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.