Errors and troubleshooting¶

How to read DKS public API errors, what failure_message means, and what to do in common situations.

Who can do this: anyone calling the API or using the console. Mutations still require super_admin.

Error body shape¶

Most 4xx/5xx responses look like:

{ "detail": "cluster 3f9c1a2e-7b4d-4c58-9e21-5d6f8a0b1c2d not found" }

detail is a string for handler-raised errors.

422 validation uses an array:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "String should match pattern …",
      "type": "string_pattern_mismatch"
    }
  ]
}

Every route and response schema is in the API reference.

HTTP status codes (public API)¶

These are the codes /v1/public/clusters… and /v1/catalog return.

400 Bad Request¶

401 Unauthorized¶

402 Payment Required¶

Prepaid organizations only (enterprise invoice orgs skip this gate).

403 Forbidden¶

You are authenticated but not allowed.

List/get as member is allowed. Kubeconfig download is allowed for member unless your operator has tightened that setting.

404 Not Found¶

A cluster that exists in another organization typically returns 403, not 404. The list endpoint is org-scoped and will not show it.

409 Conflict¶

422 Unprocessable Content¶

Schema or merged pool bounds: extra fields (extra="forbid"), missing required fields, count/auto_scale/min_nodes/max_nodes combination, empty PATCH (at least one of: tags, description or pool fields), count=0 without autoscaling.

502 Bad Gateway¶

Auth or Door hub checks failed (for example hub environments could not be torn down on ?force=true). Retry shortly. If it persists, contact Door support with the cluster id.

503 Service Unavailable¶

500 Internal Server Error¶

Unexpected server failure (including a kubeconfig that cannot be decrypted or rewritten). Retry once, then contact support with the cluster id. Do not send tokens.

failure_message on a Failed cluster¶

When phase is Failed (or a delete is stuck with a failure), failure_message is server-authored customer copy. It is never raw platform text.

progress.title is Setup failed. progress.message matches failure_message.

Common situations¶

Cluster stays in Provisioning¶

Follow GET …/state or the console Provisioning page. Copy comes from progress.title / progress.message. There is no published maximum duration in the API. Stay on the progress view until Provisioned or Failed. If progress does not move for a long time, contact Door support with the cluster id. Do not issue overlapping creates with the same name.

Kubeconfig returns 202 in a loop¶

202 means a fetch was queued. Response includes retry_after_seconds (platform default 5) and header Retry-After. Call the same GET again after that delay. Need ControlPlaneReady or Provisioned (409 otherwise). If 202 continues for many minutes after Provisioned, contact support with the cluster id.

kubectl times out on a private cluster¶

exposure_mode=private means the API is not on the Internet. Connect from your private network or VPN, use the kubeconfig downloaded after the cluster is private (server: is private_api_server_endpoint, port 6443). If you expected the Internet hostname, switch to public exposure and download kubeconfig again (server: is https://<fqdn> on 443).

Node count lower than desired¶

Desired size is node_pools[].count (or autoscaler bounds). Listed workers come from a snapshot that can be empty (cold) or briefly behind (stale). Wait until Provisioned, refresh the Nodes tab, and check ready. Autoscaling may sit at min_nodes. Failed nodes show status: Failed. If desired count stays higher than Ready workers after the pool operation has finished, contact support with the cluster id.

Delete takes a long time¶

202 then phase=Deleting. Progress message: Removing your cluster's resources. This can take a few minutes. Default list hides deleting rows; use include_deleted=true. Success is Deleted then 404. Hub environments block delete with 409 until you remove them or pass force=true.

Exposure PATCH 400 vs 409¶

Not Provisioned → 400. Another change still applying → 409, retry.

Contact Door support¶

Use your Door account team / Door support channel (no public ticket URL is published in this API). Always include:

• Cluster id (UUID), not only the name
• Organization slug (acme)
• Zone (abidjan)
• Approximate time and the failure_message or HTTP detail (never the Bearer token)

The generic setup failure sentence already embeds ref {cluster_id} so support can find the cluster.

Related¶

• Limits
• API reference
• Authentication