> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error code cliqd returns, with its HTTP status.

Every failure has the same body:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{ "ok": false, "error": { "code": "TEAM_NOT_FOUND", "message": "Team 'acme/code-review' not found" } }
```

Switch on `error.code`: codes are stable, messages are not. `error.details` is present when there is structured detail (schema issues, missing agents, …). Each endpoint page lists the codes it can return and when.

## general

| Code | HTTP | Meaning |
| - | - | - |
| `BAD_REQUEST` | 400 | Missing or invalid request |
| `UNAUTHORIZED` | 401 | Authentication required |
| `FORBIDDEN` | 403 | Forbidden |
| `NOT_FOUND` | 404 | Resource not found |
| `METHOD_NOT_ALLOWED` | 405 | Method not allowed |
| `CONFLICT` | 409 | Conflict with existing state |
| `PAYLOAD_TOO_LARGE` | 413 | Request content exceeds the allowed size |
| `UNPROCESSABLE` | 422 | Unprocessable entity |
| `INPUT_REQUIRED` | 206 | Additional user input is needed to proceed |
| `INTERNAL_ERROR` | 500 | Internal server error |
| `NOT_IMPLEMENTED` | 501 | Not implemented |
| `SERVICE_UNAVAILABLE` | 503 | Service unavailable |

## validation

| Code | HTTP | Meaning |
| - | - | - |
| `PAYLOAD_INVALID` | 400 | Payload failed schema validation |

## workspace

| Code | HTTP | Meaning |
| - | - | - |
| `WORKSPACE_ALREADY_INITIALIZED` | 409 | Workspace already has a .cliq/ directory |
| `WORKSPACE_NOT_INITIALIZED` | 404 | No .cliq/ directory found |
| `WORKSPACE_NOT_REGISTERED` | 404 | Workspace is not registered with the daemon |
| `WORKSPACE_PATH_INVALID` | 400 | Workspace path is invalid or does not exist |
| `WORKSPACE_NOT_ASSEMBLED` | 409 | Workspace has no team assembled |
| `WORKSPACE_RUN_ALREADY_ACTIVE` | 409 | Workspace already has an active run |
| `WORKSPACE_RUNS_ACTIVE` | 409 | Runs are in progress in this workspace |
| `WORKSPACE_SCOPE_MISMATCH` | 409 | Workspace and team belong to different scopes |
| `WORKSPACE_BAD_REQUEST` | 400 | Invalid workspace operation |

## team

| Code | HTTP | Meaning |
| - | - | - |
| `TEAM_NOT_FOUND` | 404 | Team not found in catalog |
| `TEAM_ALREADY_EXISTS` | 409 | Team with this scope and slug already exists |
| `TEAM_MANIFEST_INVALID` | 422 | Team manifest failed validation |
| `TEAM_ALREADY_INSTALLED` | 409 | Team is already installed |
| `TEAM_NOT_IN_REALM` | 409 | The team isn't on this cliqd's realm team list |
| `TEAM_VALIDATE_FAILED` | 400 | Team failed validation |
| `TEAM_SOURCE_INVALID` | 400 | Team source ref is invalid |
| `TEAM_VERSION_CONFLICT` | 409 | Version must be strictly higher than the current version |
| `TEAM_PHASE_REF_INVALID` | 400 | A type:team phase has a missing or malformed team ref |
| `TEAM_TREE_CYCLE` | 422 | Recursive team tree contains a cycle |
| `TEAM_TREE_TOO_DEEP` | 422 | Recursive team tree exceeds the maximum allowed depth |
| `TEAM_TREE_TOO_LARGE` | 422 | Recursive team tree exceeds the maximum allowed size |
| `TEAM_AGENT_CONFIG_REQUIRED` | 422 | Team requires agents that are missing or unconfigured |
| `TEAM_NOT_INSTALLED` | 400 | Team is not installed on this daemon |
| `TEAM_HUB_PROTECTED` | 403 | Hub-origin team cannot be overwritten without --force |
| `TEAM_VERSION_AMBIGUOUS` | 409 | Team has multiple versions; specify @version or --latest |
| `TEAM_ALREADY_ASSEMBLED` | 409 | Another version of this team is already assembled in the workspace |

## agent

| Code | HTTP | Meaning |
| - | - | - |
| `AGENT_NOT_FOUND` | 404 | Agent is not registered |
| `AGENT_ALREADY_REGISTERED` | 409 | Agent is already registered |
| `AGENT_ALREADY_EXISTS` | 409 | Agent already registered on Hub (use --force) |
| `AGENT_FORBIDDEN` | 403 | Cannot modify system agent |
| `AGENT_MANIFEST_INVALID` | 400 | Agent manifest is invalid |

## instance

| Code | HTTP | Meaning |
| - | - | - |
| `INSTANCE_NOT_FOUND` | 404 | Instance not found |

## run

| Code | HTTP | Meaning |
| - | - | - |
| `RUN_NOT_FOUND` | 404 | Run not found |
| `ORCHESTRATOR_FAILED` | 500 | Orchestrator process failed to start |
| `RUN_MISSING_INPUTS` | 400 | Required inputs were not provided |
| `RUN_INVALID_STATE` | 409 | Run is in an invalid state for this operation |
| `RUN_INVALID_PHASE` | 400 | Phase not found in team manifest |
| `RUN_MISSING_ARTIFACT` | 400 | Required phase artifact is missing |
| `RUN_INPUTS_REQUIRED` | 400 | The run needs inputs before its first phase |
| `RUN_AGENT_NOT_READY` | 400 | Agents the run needs are missing or unconfigured |

## command

| Code | HTTP | Meaning |
| - | - | - |
| `TEAM_REF_REQUIRED` | 400 | team\_id, or scope and slug are required |
| `DAEMON_ID_UNKNOWN` | 503 | daemon\_id unknown |
| `HUB_CREDENTIALS_MISSING` | 503 | no hub credentials |
| `CLAIM_FAILED` | 502 | Hub refused the claim |

## scope

| Code | HTTP | Meaning |
| - | - | - |
| `SCOPE_ALREADY_EXISTS` | 409 | A scope with this slug already exists |
| `SCOPE_IN_USE` | 409 | Scope is bound to one or more workspaces — remove them first |
| `SCOPE_NOT_FOUND` | 404 | Scope not found |

## settings

| Code | HTTP | Meaning |
| - | - | - |
| `SETTING_KEY_UNKNOWN` | 404 | Settings key is not defined |
| `SETTING_VALUE_INVALID` | 400 | Settings value failed validation |
| `SETTING_PULL_FAILED` | 502 | Failed to pull org settings from Hub |

## hub

| Code | HTTP | Meaning |
| - | - | - |
| `HUB_NOT_CONFIGURED` | 422 | Hub credentials or registry URL not configured |
| `HUB_PUBLISH_FAILED` | 502 | Hub registry rejected the publish request |
| `HUB_VERSION_ALREADY_EXISTS` | 409 | That team version is already published on Hub |
| `HUB_SEARCH_FAILED` | 502 | Hub team search request failed |
| `HUB_REQUEST_FAILED` | 502 | Hub API request failed |

## login

| Code | HTTP | Meaning |
| - | - | - |
| `LOGIN_STANDALONE` | 403 | Daemon is running in standalone mode |
| `HUB_LOGIN_FAILED` | 401 | CliqHub rejected the username or password |
| `NOT_LOGGED_IN` | 401 | Not logged in to CliqHub |
| `LOGIN_REALM_NOT_FOUND` | 404 | That realm isn't one of your realms |
| `LOGIN_REALM_AMBIGUOUS` | 409 | That name matches more than one of your realms |
| `LOGIN_NO_REALMS` | 403 | You aren't a member of any realm on CliqHub |
| `LOGIN_NOT_MEMBER` | 403 | You aren't a member of the realm this cliqd is in |
| `LOGIN_REALM_LOCKED` | 403 | Moving cliqd to another realm needs --allow-realm-override |
| `LOGIN_REALM_PINNED` | 409 | cliqd's realm is set by CLIQ\_DAEMON\_TOKEN |
| `LOGIN_RUNS_ACTIVE` | 409 | Runs are in progress on this cliqd |
| `LOGIN_TEAMS_NOT_IN_REALM` | 409 | Some of this cliqd's teams aren't in that realm |
| `LOGIN_REALM_TEAMS_UNAVAILABLE` | 503 | Couldn't read that realm's team list |
| `LOGIN_UNSYNCED_WORK` | 409 | This cliqd has work for its realm that hasn't synced yet |

## guard

| Code | HTTP | Meaning |
| - | - | - |
| `WEB_REQUEST_REFUSED` | 403 | cliqd doesn't accept requests from web pages |
| `HOST_NOT_LOCAL` | 403 | cliqd only answers requests addressed to localhost |
| `LOCAL_ONLY` | 403 | This cliqd isn't connected to CliqHub yet, so from another machine it only accepts a local token (minted by tokens/create on the machine running cliqd) |
| `SETTING_LOCAL_ONLY` | 403 | This can only be done on the machine running cliqd (settings, local tokens, sign-in) |
| `FOREIGN_HUB_REFUSED` | 403 | cliqd won't send your CliqHub sign-in to another site |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.