Error codes

Every non-2xx response from the control plane returns a stable JSON envelope:

error envelope

{
  "error": {
    "code": "CP_PROJECT_NOT_FOUND",
    "message": "no active project with that wok_id in this org",
    "hint": "verify the wok_id and that it belongs to your org",
    "correlation_id": "1aee612b1250f276"
  }
}

code is the stable machine-readable identifier — classify on this. message is human-prose. hint is the remediation. correlation_id echoes back the cp's per-request id; include it when filing a ticket so the operator can pull the journal.

Below: the codes a customer is most likely to hit, with the side that fixes each (caller = your client code; state = the wok or org needs to be in a different state; platform = open a ticket).

Authentication & authorization

Code	HTTP	Fix side	Remediation
`CP_UNAUTHENTICATED`	401	caller	Send `Authorization: Bearer <skl_…>` (or `sllm_…` for the LLM gateway). Sessions and bootstrap tokens both work where listed.
`CP_INVALID_KEY`	401	caller	The Bearer doesn't match the expected shape (`skl_<hex>` or `sllm_<hex>`). Check for whitespace + truncation.
`CP_LLM_KEY_INVALID`	401	caller	The `sllm_` key has been revoked or doesn't exist. Mint a fresh one via `POST /v1/llm-keys`.
`CP_INVALID_CREDENTIALS`	401	caller	Email/password on `/login` don't match. Re-check the credentials.
`CP_WEAK_PASSWORD`	400	caller	Sign-up password doesn't meet the 8+ character minimum.
`CP_USER_NOT_IN_ORG`	403	caller	The Bearer is valid but the caller isn't a member of the requested org. Either pass the right `slug` or have the org owner invite you.

Not found / wrong state

Code	HTTP	Fix side	Remediation
`CP_ROUTE_NOT_FOUND`	404	caller	No route at that `METHOD PATH`. Typically a URL typo. The `message` echoes back the method + path so you can spot the typo. See API reference for the canonical endpoint catalogue.
`CP_METHOD_NOT_ALLOWED`	405	caller	The path exists but the HTTP method doesn't. e.g. `DELETE /v1/healthz` when `healthz` only accepts GET. Check the route's allowed methods in API reference.
`CP_PROJECT_NOT_FOUND`	404	caller / state	No active wok with that id in this org. Note: cross-org access deliberately returns 404 not 403, to avoid enumeration. Verify via `GET /v1/woks`.
`CP_ORG_NOT_FOUND`	404	caller	No org with that slug. Slugs are case-sensitive.
`CP_NOT_ACTIVE`	409	state	The wok is destroyed (terminal). Provision a fresh one via `POST /v1/woks`.
`CP_STATUS_STALE`	503	state	The wok status row hasn't been refreshed by the reconciler yet. Retry in 5s.
`CP_FUNCTION_NOT_FOUND`	404	caller / state	No function with that name on the wok. List via `GET /v1/woks/{id}/functions`.
`CP_RELEASE_SOURCE_MOVED`	409	state	Wok Git changed while an SSR artifact was being built. Rebuild from the current checkout; the stale bundle was rejected before deployment.
`CP_RELEASE_ROLLBACK_INVALID`	400 / 409	caller / state	The target is not a source-linked successful release, is absent from Wok Git, or is already current. Select `rollback_target.id` from `get_release_status`.
`CP_RELEASE_ROLLBACK_FAILED`	500	state / platform	The rollback could not redeploy. Inspect its rollback and compensation details; TellWang attempts to replay the prior source so partial code is not left live.
`CP_RELEASE_UNVERIFIED`	diag	caller / state	Source, artifact, or runtime-check evidence is incomplete. Inspect `get_release_status` and run the missing browser/function probe.
`CP_RELEASE_FAILED`	diag	caller / state	The live receipt has source divergence, artifact drift, or a failed check. Repair the named signal and create a new verified release.
`CP_TRIGGER_NOT_FOUND`	404	caller	No installed trigger with that name. List via `GET /v1/woks/{id}/triggers`.

Validation

Code	HTTP	Fix side	Remediation
`CP_BAD_JSON`	400	caller	Request body isn't valid JSON, or required fields are missing. The `message` names the field.
`CP_INVALID_NAME`	400	caller	Identifier doesn't match the expected regex (e.g. wok ids `^[a-z][a-z0-9]{0,30}$`, env-var names `^[A-Z][A-Z0-9_]{0,63}$`). The `message` spells out the actual regex.
`CP_INVALID_BODY`	400	caller	JSON-valid but semantically wrong (e.g. bulk-env with both `vars` and `dotenv`, or cron expression that doesn't parse).
`CP_BULK_TOO_LARGE`	413	caller	Batch exceeds the per-call cap (200 vars on bulk env). Split into multiple requests.
`CP_SQL_TOO_LARGE`	413	caller	`exec_sql` body exceeds 1 MiB. Split into smaller migrations.
`CP_LLM_BODY_TOO_LARGE`	413	caller	LLM chat-completions body exceeds 1 MiB. Trim history or use a smaller system prompt.

Capacity & rate limits

Code	HTTP	Fix side	Remediation
`CP_WOK_QUOTA_EXCEEDED`	402	caller	You're at your plan's wok limit. Upgrade via `POST /v1/orgs/{slug}/billing/checkout/subscription` or delete an unused wok.
`CP_LLM_MODEL_UNSUPPORTED`	400	caller	Set `model:"private"`.
`CP_LLM_PROVIDER_DISABLED`	410	caller	External provider and BYOK routing is inactive.
`CP_LLM_INSUFFICIENT_BALANCE`	402	caller	The prepaid model allowance is empty.

Upstream / platform

Code	HTTP	Fix side	Remediation
`CP_DB_QUERY_FAILED`	500	platform	The cp's own Postgres returned an error. Check `GET /v1/diag` for the `cp_db` subsystem; file a ticket with `correlation_id`.
`CP_DUMP_DB_NOT_READY`	503	state	Wok's db container hasn't finished provisioning. Retry in 5–10s.
`CP_EXEC_SQL_FAILED`	502	state	The docker-exec call into the wok's db container failed (often because it's restarting). Retry; if persistent, hit `/diag/wok/{id}`.
`CP_LLM_UPSTREAM_FAILED`	502	platform	The private LLM upstream returned an invalid response or timed out.
`CP_LLM_NOT_CONFIGURED`	503	platform	The private LLM password is missing from the platform secrets backend.
`CP_EMAIL_UPSTREAM_FAILED`	502	platform	The Resend API call failed. The `message` echoes Resend's status. Common cause: the sending domain hasn't been verified yet.
`CP_DOMAIN_UPSTREAM_FAILED`	502	platform	Cloudflare Registrar or DNS API call failed. The `message` echoes CF's response.
`CP_FUNCTIONS_NOT_ENABLED`	503	state	This wok was provisioned before functions shipped and has no `functions_port` allocated. The reconciler heals this on its next sweep, or call `POST /v1/woks/{id}/restart` to force it.

Managed RAG

Code	HTTP	Fix side	Remediation
`CP_RAG_NOT_ENABLED`	409	state	Enable the optional runtime with `PUT /v1/woks/{id}/rag` and wait for `status:"ready"`.
`CP_RAG_DEPLOY_FAILED`	502	state / platform	Inspect `/diag/wok/{id}` and the `rag-api` plus `rag-worker` service logs.
`RAG_INGESTION_IN_PROGRESS`	409	state	One atomic revision is already building. Poll its parent job to a terminal state before submitting the next manifest.
`RAG_FORBIDDEN`	403	caller / policy	The caller lacks the required management or author role, or anonymous chat is disabled for this agent. Use the intended signed role, or deliberately enable anonymous access only for a public agent.
`RAG_RATE_LIMITED`	429	caller	The end-user principal/client exceeded its one-minute retrieval, chat, generation, or insight allowance. Wait for the returned window; keep service-role calls server-side.
`RAG_INGESTION_BATCH_FAILED`	job	caller / state	The old revision remains active. Repair the failed child documents, then retry with a new idempotency key.
`RAG_POLICY_FILTER_FAILED`	500 / job	platform	Retrieval stopped before a model call because the SQL result and application policy disagreed. Disable the affected agent and reconcile the collection.
`RAG_NO_PERMITTED_SOURCES`	job	caller	The signed user cannot read any requested source. Correct the document allow/deny policy or use the intended group and sensitivity ceiling.
`RAG_PARSE_TIMEOUT`	job	caller	The isolated parser exceeded its wall-clock or CPU budget. Inspect or convert the source, then submit a new atomic batch.
`RAG_MODEL_BUDGET_EXCEEDED`	job	caller	The governed map-reduce job reached `max_model_calls`. Raise the bounded cap when the cost is intentional, or partition the corpus.

Beyond this list

For every other code emitted by the cp, the response envelope's hint field gives the same remediation a customer support reply would. Hits to /diag (see Diagnostics) are the canonical "what's wrong" surface; correlation_id ties a single request across cp logs + downstream container logs + the audit log.