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_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_INSUFFICIENT_BALANCE`	402	caller	Both prepaid meters (tokens + requests) have hit zero. Top up via `POST /v1/llm-keys/{prefix}/topup`, or configure BYOK via `PUT /v1/orgs/{slug}/llm-byok` to pay the upstream directly.

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 / BYOK	The configured LLM upstream (DeepSeek default or your BYOK URL) returned a non-2xx or timed out. Check upstream status; the `X-LLM-Source` response header tells you which side answered.
`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.

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.