Errors

Error codes, response format, and troubleshooting guidance for the OneCLI API.

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

Policy rules

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

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