Errors - OneCLI

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.

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	Choose a different identifier. Use the list endpoint to see existing resources.
`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

Rules

Error message	Status	Cause
`"rateLimit and rateLimitWindow are required when action is rate_limit"`	400	Action set to `rate_limit` without the required rate fields
`"Rate limit rules require a rate limit and window"`	400	Update would leave a `rate_limit` rule without a valid rate configuration
`"At least one field must be provided"`	400	PATCH request with an empty body
`"Policy rule not found"`	404	Rule ID doesn’t exist
`"Unknown tool: {toolId}"`	400	Permission change references a tool ID not in the app’s permission definition
`"Only agent-scoped app permissions can be set to inherit"`	400	`inherit` sent without `agentId`

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

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	Use a different identifier
`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

Overview Partner API

​Error response format

​Error reference

​Common error messages

​General

​Agents

​Secrets

​Rules

​Apps

​User

​Retry guidance