# Errors

Every HQ API error is an RFC 9457 problem document. This page lists every code.



An error answers with `Content-Type: application/problem+json`:

```json
{
  "type": "https://hq.aiworkforceone.com/docs/api/errors/#not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No such team.",
  "request_id": "6f1c2a…"
}
```

* `code` is stable; switch on it. The list of codes may grow.
* `type` links to the code's entry on this page.
* `request_id` identifies the request. Quote it when you contact support. It is also in the
  `Request-Id` response header.
* Some codes add fields: `permission`, `reason`, `errors`, `limit_scope`, `retry_after`.

## Codes [#codes]

### invalid_request [#invalid_request]

`400`. A query parameter, header or body is malformed or unknown. `errors[]` names each field and
why, for example `{ "field": "bogus", "code": "unknown_parameter" }`. An unknown name longer than 64
characters is cut to 64, ending in `…`, in `errors[].field` and in `detail`. Fix the request;
retrying it unchanged fails again.

### invalid_credentials [#invalid_credentials]

`401`. The key is missing, malformed, unknown, revoked, expired, switched off for being unused, past
its roll date, or for the other environment. The answer is the same for every case on purpose. Check the key in HQ.

### permission_denied [#permission_denied]

`403`. The key does not hold the permission the request needs, or its person or role no longer can.
`permission` names it. Add the scope (create a new key) or ask an owner for the access. A key
restricted to some AI teams gets this on `GET /audit_events`: the audit log covers the whole
organization, so it needs a key for all teams.

An [agency key](/docs/api/agency-keys/) also gets `reason`: `delegation_ceiling` when no agency key can
ever do this in a client (a secret value, a keystroke in a session, a schedule change, …), or when
the key is not linked to that client; `agency_access_level` when the client's access level for its
provider does not include it. Without `reason`, the key itself was not created with that scope.

When the key has the scope but the person it acts as (or, for a service key, its role) does not
have the permission, `reason` is `holder_permission`: the key is fine, and the fix is the person's
access, not a new key. Ask an owner or admin to change their role.

### protected_path [#protected_path]

`403`. The AI team protects this file (its owners turned on Protected files), and the key, or the
person it acts as, may not open or change it. A key needs the `files:protected.read` scope to open
protected files and `files:protected.write` to change them, and its person needs the same
permissions on the team. `detail` says which. Listings show such a file or folder as one entry with
`protected: true`. Ask an owner of the team for access.

### ip_not_allowed [#ip_not_allowed]

`403`. The key has an IP allowlist and this request came from outside it.

### two_factor_required [#two_factor_required]

`403`. Your organization requires two-factor authentication, and the person this key acts as has not
turned it on. They turn it on in HQ, and the same key works again. Service keys are not affected.

### third_party_apps_disabled [#third_party_apps_disabled]

`403`. An [OAuth app](/docs/api/oauth/)'s token, in an organization whose owners or admins turned
third-party apps off. The app works again when they turn them back on in **Settings**,
**Developers**. API keys, and apps the organization registered itself, are not affected.

### plan_required [#plan_required]

`403`. Your organization's plan does not include the API right now, or its subscription has ended.

### client_access_disabled [#client_access_disabled]

`403`. An [agency key](/docs/api/agency-keys/) named a client that has turned its provider's access
off. Only the client's owner can turn it back on.

### agency_suspended [#agency_suspended]

`403`. An [agency key](/docs/api/agency-keys/)'s agency account is not active (suspended, or more
than 3 days past due), so its keys cannot act for its clients. Also every change to a client whose
provider's account was suspended: the client can still read its data.

### org_suspended [#org_suspended]

`403`. HQ Support has suspended changes to your organization. Every request that changes something
gets this; reading still works, and a key can still revoke itself. Contact support to restore changes.

### not_found [#not_found]

`404`. The object does not exist, belongs to another organization, is outside the key's AI teams, or
the id has the wrong prefix (a `team_` id where a `sess_` id belongs). These cases are
indistinguishable on purpose.

### team_restricted [#team_restricted]

`403`. The key is restricted to some AI teams, and the request would change something that reaches
the whole organization: an org-wide secret or variable, an invitation, a new AI team, a webhook
endpoint. Use a key for
all teams. (Within its teams the same key works: a secret shared only with them, for example.)

### session_not_owned [#session_not_owned]

`403`. The session runs on a person's own Claude account, and only that person's own user key may
type into it. See [Sessions and prompts](/docs/api/sessions-and-prompts/).

### agent_config_protected [#agent_config_protected]

`403`. A service key cannot change the AI team's agent configuration at the root of its files:
`.claude/`, `.codex/`, `CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md`, `AGENTS.override.md` and
`.mcp.json`, nor reach them through a linked folder. Use the
user key of the person making the change.

### personal_login_not_available [#personal_login_not_available]

`422`. The request needs a person (a session on their own Claude account, a schedule that runs as
them), and a service key has none. Use a user key.

### operation_conflict [#operation_conflict]

`409`. The AI team already has an operation in progress; `operation` names it. Wait for it, then
retry. The machine being changed from HQ (an update or a resize) answers the same, without
`operation`. See [Operations](/docs/api/operations/).

### computer_busy [#computer_busy]

`409`. Sessions are running on the Cloud Computer. Send `force` (stop) or `restart` (update) to go
ahead anyway.

### workspace_paused [#workspace_paused]

`409`. The AI team is paused, so none of its sessions can start (a create with `start`, a start
or a restart). A team paused after sustained heavy CPU use is cleared with
`POST /teams/{team_id}/computer/unpause` (`compute:unpause`, org owners and admins). A hold placed
by support or by your provider is lifted only by them; contact support.

### workspace_updating [#workspace_updating]

`409`. The AI team's Cloud Computer is being updated or resized, so none of its sessions can start
(a create with `start`, a start or a restart). Retry once it finishes; `GET /teams/{team_id}/computer`
shows its state.

### machine_busy [#machine_busy]

`409`. The AI team has a free session slot, but its Cloud Computer is too busy for another session:
its memory is at 80% or more, or its processor has been working at full capacity for a while.
Nothing starts (a create with `start`, a start or a restart; a create leaves the session stopped).
Stop a session you no longer need, or move the team to a bigger size, then retry. Running a
schedule now answers the same.

### protected_files_shell [#protected_files_shell]

`403`. The AI team protects its files, and the key, or the person it acts as, may not open AND
change them, so it cannot run Codex on the team: creating, starting or restarting a Codex session, or
creating, changing, enabling or running a Codex schedule. A shell can read and change any file, and
Codex runs commands. Claude sessions are not affected. Ask an owner of the team for access.

Running a schedule now answers `409` with this code instead when the key may run it but the person
the schedule runs as may not: the run is skipped, nothing starts.

### runner_needs_update [#runner_needs_update]

`409`. The AI team protects its files, and its Cloud Computer runs an image too old to enforce
that, so a key that may not open protected files is refused every file on the team until the
computer is updated. An owner updates it in HQ. Keys that may open protected files are not
affected.

### engine_unavailable [#engine_unavailable]

`409`. This session's conversation cannot be followed over the API right now (for example, its
engine is not available on the API yet).

### idempotency_in_progress [#idempotency_in_progress]

`409`. A request with the same `Idempotency-Key` is still running. Wait `Retry-After` seconds and
retry with the same key. See [Idempotency](/docs/api/idempotency/).

### idempotency_key_reused [#idempotency_key_reused]

`422`. This `Idempotency-Key` was already used for a different request. Use a new key.

### misdirected [#misdirected]

`421`. The request reached the wrong server. Retry it once, with the same `Idempotency-Key`.

### too_many_streams [#too_many_streams]

`429`. The session or the organization has as many open event streams as it may. Close one first.

### not_configured [#not_configured]

`503`. This API is not fully set up on our side. Retry later.

### payload_too_large [#payload_too_large]

`413`. The request body is too large.

### validation_failed [#validation_failed]

`422`. The request was well formed but its values were refused.

### rate_limited [#rate_limited]

`429`. Too many requests for the key (`limit_scope: "credential"`) or the organization
(`limit_scope: "org"`), or too many invalid keys from your address (`limit_scope: "ip"`). Wait `retry_after` seconds (also in the `Retry-After` header) and retry. See
[Rate limits](/docs/api/rate-limits/).

### internal [#internal]

`500`. Something went wrong on our side. Retry with backoff, and quote the `request_id` if it
persists.

### upstream_unavailable [#upstream_unavailable]

`502` or `503`. A part of HQ the request needed did not answer. Retry with backoff.
