Problem types
Every problem type the API answers with: its status, what it means and what to do.
Last updated 2026-10-19
An error of the API is a problem (Read errors) whose type is about:blank or one of
the URNs below. Branch on the type; the detail text may change between releases. hart prints the problem's text
and exits with a code from hart › Exit codes.
Each type is written here without its prefix: name-taken stands for urn:harthelm:problem:name-taken.
General
| Type | Status | What it means | What to do |
|---|---|---|---|
about:blank | any | Nothing more specific than the status. A 429 comes with Retry-After. | Read detail; for 429, wait and retry. |
name-taken | 409 | A workspace, organization or team of that name exists. | Choose another name. |
quota-exceeded | 409 | The team's quota does not fit the request. detail names each resource: "Team quota exceeded: needs …, … left." When recently deleted workspaces hold storage, held_by_deleted says how much. | Stop or delete a workspace, purge deleted ones, or ask an administrator for a larger quota. |
disk-quota-exceeded | 409 | The workspace's files use more than its volume size. Sync and prepare are refused. | Delete files in the workspace. |
wake-refused | 503 | The action needs a sleeping workspace awake and the wake was refused: no capacity, nodes off on a schedule, waking paused, or the volume busy. detail says which; Retry-After says when to try again. | Retry after Retry-After. See Status texts › Sleep and wake. |
Workspaces and Git
| Type | Status | What it means | What to do |
|---|---|---|---|
git-connection-required | 409 | You have not connected the Git provider the workspace uses. | Connect it under Settings › Git connections, then repeat. |
git-pull-failed | 409 | git pull --ff-only failed in the workspace; detail is git's output. | Resolve the divergence in the workspace's terminal. |
workspace-not-deleted | 409 | Purging needs a deleted workspace. | Delete it first. |
workspace-awake | 409 | An archive needs the editor and every service asleep. | Put the workspace to sleep, then repeat. |
backups-disabled | 409 | The installation does not keep workspace archives, or managed-service dumps are off or not supported by the provider. | Ask your administrator. |
Landscape and stages
| Type | Status | What it means | What to do |
|---|---|---|---|
invalid-config | 422 | harthelm.yml does not parse, validate or resolve. errors[] point into the file with pointer, line, column and a code from harthelm.yml errors. | Fix the file. |
plan-changed | 409 | Sync's If-Match is not the plan you reviewed: the file, the environment variables or the installation's catalog changed since. | Plan again, review, Sync. |
secrets-missing | 409 | A secret the file references has no value; errors[] name them as /secrets/<key>. | Set the secrets, then Sync. |
landscape-blocked | 409 | The plan has blockers; errors[] carry them with their codes. | See Sync blockers. |
landscape-not-synced | 409 | Run, or a service start, before the first Sync or after a teardown. | Sync first. |
stage-running | 409 | A run of this stage is active. | Wait for it, or stop it. |
config-changed | 412 | The file on disk is not the version your change is based on, or it exists although you asked to create it. | Read the file again and repeat your change. |
Managed services
| Type | Status | What it means | What to do |
|---|---|---|---|
provider-unavailable | 409 | The provider or its version is unknown, disabled, not offered to your team, or the cluster cannot run it. | Choose another provider, or ask your administrator. |
provider-builtin | 409 | A built-in provider cannot be changed through the API; the chart's values configure it. | Change the chart values. |
one-per-team | 409 | The provider allows one instance per team, and the team has one. | Use the existing one. |
managed-service-bound | 409 | The service belongs to a landscape. | Change harthelm.yml and Sync instead. Rotate, backups and (since 1.4.0) the public host still work. |
managed-service-paused | 409 | A dump or Rotate of a paused service; no server runs. | Sync the landscape to resume it first. |
managed-service-deleted | 409 | The service is being deleted or is deleted. | Nothing. |
public-hosts-disabled | 409 | The installation does not allow public hosts for managed services (since 1.4.0). Turning a public host off always works. | Keep the store's host behind the sign-in, or ask your administrator. |
update-constraint | 422 | The change breaks a rule of the provider: a value that cannot change, only grow, or only take a minor upgrade. errors[] point at the values. | Keep the value, or create a new service. |
Teams, members and invitations
| Type | Status | What it means | What to do |
|---|---|---|---|
last-owner | 409 | The change would leave the organization without an owner. | Make someone else owner first. |
last-admin | 409 | The change would leave the team without an admin. | Make someone else admin first. |
not-org-member | 409 | A team membership needs organization membership that you may not grant. | Ask an organization owner to add the user. |
not-team-member | 409 | A workspace role or ownership needs team membership. | Add the user to the team first. |
already-member | 409 | The user is a member already. | Nothing. |
already-invited | 409 | The email has a pending invitation. | Resend or revoke it. |
user-unknown | 409 | Nobody with that verified email has signed in yet. | Invite them instead. |
below-inherited-role | 409 | The workspace role is not above the role the user inherits from the team or organization. | Choose a higher role, or none. |
owner-ineligible | 409 | The new workspace owner needs the right to change code in the workspace and a connection to its Git provider. | Give them the role and ask them to connect the provider. |
owner-transfer-closed | 409 | The ownership transfer was accepted, declined or cancelled already. | Start a new transfer if needed. |
invite-invalid | 409 | The invitation was accepted, revoked or has expired, or the link is unknown. | Ask for a new invitation. |
invite-email-mismatch | 403 | Your verified email is not the one invited. | Sign in with the invited account, or ask for an invitation to your email. |
team-deleting | 409 | The team is being deleted; it takes no changes. | Nothing; the deletion cannot be undone. |
org-deleting | 409 | The organization is being deleted; it takes no changes. | Nothing. |
team-delete-failed | 500 | The error of a failed team deletion: a step kept failing. failed_team names the team, the step and its last error. The team stays in deletion. | Fix the cause (or ask your administrator), then delete again to retry. |
org-delete-failed | 500 | The error of a failed organization deletion: one of its teams could not be deleted; failed_team names it. | As above, then delete the organization again. |
The last two appear as the error of a failed operation, not as the
answer to a request.
Licence
| Type | Status | What it means | What to do |
|---|---|---|---|
license-restricted | 403 | The installation has no valid licence, or its grace period is over: new teams, organizations, workspaces, managed services, domains, invitations and users are paused. Everything that exists keeps working. | Ask your administrator to install a licence; see Licence. |
license-limit | 403 | The licence enforces a limit on users or workspaces, and the installation has reached it. | Delete a workspace you no longer use, or ask your administrator for a licence with a higher limit. |
Sign-in and API keys
| Type | Status | What it means | What to do |
|---|---|---|---|
cli-login-closed | 409 | The hart login sign-in was denied, has expired (after 10 minutes) or was used already. | Run hart login again. |
Custom domains
| Type | Status | What it means | What to do |
|---|---|---|---|
custom-domains-disabled | 409 | This installation offers no custom domains. | Ask your administrator. |
domain-taken | 409 | The name is in use by a domain of this installation, or one is being removed ("add it again in a minute"). | Use another name, or wait a minute if you just removed it. |
domain-reserved | 409 | The name belongs to the installation: its console host or its workspace domain. | Use another name. |
domain-limit | 409 | The team has the most domains allowed (20 by default). | Remove a domain you no longer use. |
domain-create-rate | 429 | The team added too many domains in the last hour (10 by default, deleted ones included). | Wait for Retry-After. |
See Custom domains.
REST API
The conventions every operation of the Harthelm API follows, and where each operation is documented.
What the cluster offers
Cluster admins only (`platform.admin`; the console's admin *Capabilities* page and `hart admin doctor --capabilities`). The last capability probe (core runs it at start and hourly; it is not re-run by this call): the Kubernetes version, the storage access core found, every optional feature with its state and, for one that is not available, the reason and what it needs, and the result of the NetworkPolicy enforcement probe that `helm test` runs.