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 }). |
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. |