Errors

The OneCLI API uses standard HTTP status codes to indicate the outcome of a request. Codes in the 2xx range indicate success, 4xx codes indicate a client error, and 5xx codes indicate a server error. This page covers the management API (api.onecli.sh/v1). Errors on an agent’s proxied traffic — requests that ride the gateway to a provider — use flat, code-tagged bodies documented separately in Gateway errors.

Error response format

Error responses come in two shapes. Route-level validation errors return a flat error string:

{
  "error": "Label is required"
}

For validation errors, the message is the first issue reported by the validator. Authentication failures and service errors use an envelope with a message and a type:

{
  "error": {
    "message": "Invalid API key or token.",
    "type": "authentication_error"
  }
}

Handle both: read error when it is a string, otherwise error.message.

Error reference

Status	Meaning	Common causes	What to do
`400`	Bad Request	Missing required field, invalid field value, body fails validation	Check the request body against the endpoint’s schema. Ensure required fields are present and values match expected types/formats.
`401`	Unauthorized	Missing or invalid API key, expired session	Verify your `Authorization` header. Regenerate your API key if needed via `POST /user/api-key/regenerate`.
`403`	Forbidden	Insufficient permissions for this resource	Confirm you are using the correct project and API key.
`404`	Not Found	Resource ID doesn’t exist, wrong provider name	Confirm the resource ID or provider name exists. Use the corresponding list endpoint to check.
`409`	Conflict	Duplicate agent identifier; a reorder list that no longer matches the draft	Choose a different identifier, or refresh and resend. (A `409` on an agent’s proxied request is the multiple-accounts protocol, not a management error.)
`410`	Gone	The endpoint was retired	The capability moved — the message says where. See the retired endpoints inventory below.
`422`	Unprocessable	The body parsed but violates a validation law	Fix the field the message names (grants tool lists, policy rule pairing).
`500`	Internal Server Error	Unexpected server failure	Retry after a brief delay. If the error persists, contact support.

Common error messages

General

Error message	Status	Cause
`"Invalid API key or token."`	401	Missing/invalid key, or an organization key (`oc_org_`) used on a project endpoint without `X-Project-Id`
`"X-Project-Id header is required"`	400	The endpoint needs a project context that the request didn’t carry
`"Insufficient permissions"`	403	The endpoint requires the admin or owner role

Agents

Error message	Status	Cause
Zod validation message for `name` (1-255 characters)	400	Empty or overly long `name` field
`"Identifier must be 1-50 characters, start with a letter or number, and contain only lowercase letters, numbers, and hyphens"`	400	Invalid identifier format
`"An agent with this identifier already exists"`	409	Duplicate `identifier` within the project (envelope shape)
`"Cannot delete the default agent"`	400	Attempting to delete the project’s default agent
`"Agent is already the default"`	400	Agent is already set as default
`"One or more secrets not found"`	400	Secret IDs in the request don’t exist in the project
`"Agent not found"`	404	Agent ID doesn’t exist

Secrets

Error message	Status	Cause
`"Enter a hostname, not a URL (remove http:// or https://)"`	400	`hostPattern` includes a protocol prefix
`"Enter a hostname only, not a path (use the path pattern field for paths)"`	400	`hostPattern` includes a `/` path
`"Host pattern must not contain spaces"`	400	`hostPattern` contains whitespace
`"Header name, parameter name, or URL path template is required for generic secrets"`	400	`type` is `generic` but `injectionConfig` has no injection method
`"1Password is only available for project-scoped secrets"`	400	`valueSource: onepassword` on an organization secret
`"No fields to update"`	400	PATCH request with an empty body
`"Secret not found"`	404	Secret ID doesn’t exist

Grants

Error message	Status	Cause
`"Custom access needs at least one allowed or approval tool — detach instead."`	422	A custom grant with both lists empty — an all-blocked grant is a detach
`"A tool can't be both always-allowed and require approval."`	422	The same tool id in `allow` and `ask`
`"Unknown tool id(s) for \"{provider}\": {ids}"`	422	Tool ids not in the provider’s catalog — read `GET /v1/apps/{provider}/permission-definition`
`"Per-tool permissions need a permission catalog; \"{provider}\" has none."`	422	A custom grant on an app without a tool catalog — use full access
`"Insufficient permissions"`	403	A non-empty `ask` list on a plan without manual approvals
`"Agent not found."` / `"Connection not found."` / `"Secret not found."`	404	The id doesn’t exist in this project’s pool

Policy rules (organization)

Error message	Status	Cause
`"rateLimit and rateLimitWindow must be provided together"`	422	One rate-limit field set without the other
`"rate-limit and approval modifiers require action = allow"`	422	`rateLimit` or `requireApproval` on a `block` rule
`"At least one field must be provided"`	422	`PATCH /v1/org/policy/rules/{ruleId}` with an empty body
`"Policy rule not found."`	404	Draft rule ID doesn’t exist (published row ids regenerate every publish; match by `logicalId`)
`"Rule set changed — refresh and try again."`	409	Reorder list didn’t name every non-default draft rule exactly once

Apps

Error message	Status	Cause
`"Unknown provider: {provider}"`	404	Provider name not in the app registry
`"Provider \"{provider}\" is not available"`	400	App exists but is not available for connection
`"Missing fields in request body"`	400	No `fields` object in connect request
`"{field} is required"`	400	A required credential field is empty
`"Connection not found"`	404	Connection ID doesn’t exist or isn’t owned by the caller
`"Label is required"`	400	Rename request without a non-empty `label`
`"Invalid request body"`	400	BYOC config body missing the app’s required credential fields

User

Error message	Status	Cause
Zod validation message (e.g. `"Too small: expected string to have >=1 characters"`)	400	Empty or overly long `name` field

Retired endpoints (410)

The move to agent grants retired the legacy rules model and the project-scope policy CRUD. Retired paths answer 410 Gone with a message that names the replacement — the pointer differs by scope, because the capability split: project access is written through grants, while organization rules keep the full policy console. Project-scope tombstones end with:

Project access is granted per agent: PUT /v1/agents/:agentId/grants/connections/:connectionId and /v1/agents/:agentId/grants/secrets/:secretId.

Organization-scope tombstones end with:

Use /v1/org/policy — one first-match rule set covering blocks, allows, rate limits, approvals and app permissions.

Retired path	What the message says	Where it went
`/v1/rules/*`	`/v1/rules was removed.`	Grants (project)
`/v1/rules/permissions/{provider}`	App permissions are policy rules with an app target; tool catalog at `/v1/apps/permission-definitions`	Grants + catalog
`/v1/rules/overlap/{provider}`	Overlap is computed by the organization Policy console	Org console
`/v1/org/rules/*`	`/v1/org/rules was removed.`	`/v1/org/policy/*`
`/v1/org/settings`	The allow/deny posture is the scope’s Default Rule	`/v1/org/policy/default`
`PATCH /v1/agents/{agentId}/secret-mode`	Agents are always selective now; attach credentials with the grants endpoints	Grants
`/v1/agents/{agentId}/secrets`	Grant a secret to the agent instead	`PUT …/grants/secrets/{secretId}`
`/v1/agents/{agentId}/connections`	Grant a connection to the agent instead	`PUT …/grants/connections/{connectionId}`
`/v1/agents/granular-access`	Resource scoping rides the granting rule’s conditions	Rule conditions
`/v1/policy/rules`, `/v1/policy/rules/{ruleId}`, `PUT /v1/policy/rules/order`	Removed at project scope: project rules are compiled from agent credential grants, not authored directly	Grants
`/v1/policy/default`, `POST /v1/policy/publish`, `GET /v1/policy/last-publish`	Removed at project scope (same message)	Grants / org policy
`/v1/connections/{connectionId}/agents`	An agent reaches a connection through its grant; `GET …/effective-agents` reports who can, read-only	Grants + reflection

GET /v1/policy/effective-app-permissions is not retired — it is the surviving project-scope reflection.

Retry guidance

Most 4xx errors are not retryable. They indicate a problem with the request that must be fixed before retrying.

Status	Retryable?	Notes
`400`	No	Fix the request body
`401`	No	Fix authentication
`403`	No	Check permissions
`404`	No	Fix the resource ID or path
`409`	No	Refresh state or change the identifier (proxied 409s: add the connection header)
`410`	Never	Permanent — move to the replacement endpoint
`422`	No	Fix the field the message names
`500`	Yes	Retry with exponential backoff

For 500 errors, retry with exponential backoff:

# Simple retry with backoff
for i in 1 2 3; do
  response=$(curl -s -w "\n%{http_code}" \
    -H "Authorization: Bearer $ONECLI_API_KEY" \
    https://api.onecli.sh/v1/agents)

  status=$(echo "$response" | tail -1)
  [ "$status" -ne 500 ] && break

  sleep $((2 ** i))
done

Agents

Grants

Secrets

Apps

Connections

Effective policy

Projects

Team

User

Utility

Agent Setup

Migration

Approvals

Organization Secrets

Organization Policy

Organization Connections

Organization App Config

Organization Approvals

Partner Organizations

Partner Projects

Partner Secrets

Partner Budgets

Partner Members

Organization Partner

Error response format

Error reference

Common error messages

General

Agents

Secrets

Grants

Policy rules (organization)

Apps

User

Retired endpoints (410)

Retry guidance

​Error response format

​Error reference

​Common error messages

​General

​Agents

​Secrets

​Grants

​Policy rules (organization)

​Apps

​User

​Retired endpoints (410)

​Retry guidance

Error response format

Error reference

Common error messages

General

Agents

Secrets

Grants

Policy rules (organization)

Apps

User

Retired endpoints (410)

Retry guidance