> ## 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 the CliqHub API returns, with its HTTP status and what it means.

Every failure has `ok: false`, the HTTP status of the error, and one of two bodies. Both always carry a code.

| Body | When |
| - | - |
| `{ "ok": false, "error": { "code": "forbidden", "message": "You do not have access to do this" } }` | An access check refused the call: 401, 403, 404 (also when you cannot see the record), and 400 when neither `realm_id` nor `org_id` was sent; and `route_not_found` for an unknown endpoint. |
| `{ "ok": false, "error": "Team @acme/code-review already exists", "code": "conflict" }` | The endpoint refused it. `error` is the message, `code` the reason, `details` structured detail when there is some (for `invalid_params` from a schema check: `details.issues`, each `{ field, message }`). |

Switch on the code: codes are stable, messages are for people and may change. An error with no more specific code gets the code for its HTTP status (`bad_request`, `forbidden`, `not_found`, `conflict`, …). Each endpoint page lists the errors it can return, with an example of each and when it happens.

| Code | HTTP | Meaning |
| - | - | - |
| `bad_request` | 400 | The request is missing something the route needs before it can be checked, such as `realm_id` or `org_id` on a route that takes either. |
| `invalid_request` | 400 | The request is well-formed but cannot be carried out as asked (for example an unsupported combination of fields). |
| `missing_run_id` | 400 | `run_id` was not sent in the query string. |
| `sign_in_required` | 401 | The invited person already has an account and must sign in to accept. `details.invitee_email` says who. |
| `unauthorized` | 401 | No token, or the token is malformed, expired or revoked. |
| `account_deleted` | 403 | The account was deleted; it cannot sign in or sign up again. |
| `email_mismatch` | 403 | You are signed in as someone other than the person the invitation is for. |
| `forbidden` | 403 | The token is valid but its user (or daemon) may not do this: the role is too low, a permission is missing, or the wrong kind of token was used. |
| `team_not_in_org` | 403 | The team does not belong to the organization named in the request. |
| `not_found` | 404 | The record does not exist, or it exists in a realm or organization you cannot see. CliqHub answers 404 rather than 403 so it does not reveal which. |
| `route_not_found` | 404 | There is no such endpoint on this CliqHub (`Unknown API route: POST /v1/…`). Check the path, or the CliqHub version. |
| `agent/in_use` | 409 | The agent cannot be deregistered while published teams still use it. The message names them. |
| `already_member` | 409 | The invited person is already an active member. |
| `conflict` | 409 | The name (slug, username, email, version) is already taken. `details` names the field and the record holding it. |
| `deleted` | 409 | The name belongs to a deleted organization or user. A site administrator may reactivate it. `details` describes the deleted record. |
| `invite_required` | 409 | The person is not a member of the realm yet; send them an invitation instead. |
| `locked` | 409 | A built-in rule or channel cannot be changed or removed. `details.system_key` names it. |
| `not_active` | 409 | The user is not active (for example suspended). |
| `not_pending` | 409 | The invitation or link was already used, declined or revoked. `details.status` says which. |
| `owns_orgs` | 409 | The user still owns organizations; transfer or delete them first. `details.orgs` lists them. |
| `run/daemon_offline` | 409 | The run's daemon has not sent a heartbeat for over a minute, so it cannot take the command now. Wait for it to reconnect and try again. |
| `run/daemon_stranded` | 409 | The run's daemon no longer exists or has been offline for over 24 hours; the run's local state is gone. Start a new run. |
| `run/stranded` | 409 | CliqHub cannot tell which daemon ran the run, so it cannot be controlled. Start a new run. |
| `team_in_use` | 409 | The team is still used (installed or referenced), so it cannot be removed yet. |
| `expired` | 410 | The invitation or password link has expired. `details.expired_at` says when. Ask for it to be sent again. |
| `artifact_too_large` | 413 | The artifact is larger than CliqHub accepts. |
| `payload_too_large` | 413 | The request or file is larger than allowed. |
| `content_blocked` | 422 | A message was blocked by the content filter. |
| `invalid_package` | 422 | The uploaded team package is not valid (missing or broken `team.yml`). |
| `invalid_params` | 422 | The body fails the endpoint's schema, or a value is not acceptable (bad format, reserved name). The message lists each problem as `field: problem`; some carry `details.field`. |
| `rate_limited` | 429 | Too many requests. Wait and try again. |
| `error` | 500 | A failure whose HTTP status has no code of its own (rare). |
| `generation_failed` | 500 | Building a team with AI failed. The message says why; try again or change the request. |
| `internal` | 500 | An unexpected server fault (older code for `internal_error`). |
| `internal_error` | 500 | An unexpected server fault. Retry later; if it persists, report it with the time of the request. |
| `service_unavailable` | 503 | A service CliqHub needs is not available or not configured (for example file storage). Try again later. |
| `storage_not_configured` | 503 | This CliqHub has no file storage configured, so artifacts cannot be stored. |


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