AI Workforce OneHQDocs

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:

{
  "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

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

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

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 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

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

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

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

403. An OAuth app'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

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

client_access_disabled

403. An agency key named a client that has turned its provider's access off. Only the client's owner can turn it back on.

agency_suspended

403. An agency key'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

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

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

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

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.

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

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

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.

computer_busy

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

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

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

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

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

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

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

409. A request with the same Idempotency-Key is still running. Wait Retry-After seconds and retry with the same key. See Idempotency.

idempotency_key_reused

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

misdirected

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

too_many_streams

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

not_configured

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

payload_too_large

413. The request body is too large.

validation_failed

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

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.

internal

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

upstream_unavailable

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