Skip to main content
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

All error responses return a JSON object with an error field: 
{
  "error": "Agent with this identifier already exists"
}
For validation errors, the message is the first issue reported by the validator.

​
Error reference

StatusMeaningCommon causesWhat to do
400Bad RequestMissing required field, invalid field value, body fails validationCheck the request body against the endpoint’s schema. Ensure required fields are present and values match expected types/formats.
401UnauthorizedMissing or invalid API key, expired sessionVerify your Authorization header. Regenerate your API key if needed via POST /user/api-key/regenerate.
403ForbiddenInsufficient permissions for this resourceConfirm you are using the correct project and API key.
404Not FoundResource ID doesn’t exist, wrong provider nameConfirm the resource ID or provider name exists. Use the corresponding list endpoint to check.
409ConflictDuplicate agent identifierChoose a different identifier. Use the list endpoint to see existing resources.
500Internal Server ErrorUnexpected server failureRetry after a brief delay. If the error persists, contact support.

​
Common error messages

​
Agents

Error messageStatusCause
"Agent name must be 1-255 characters"400Empty or overly long name field
"Identifier must be 1-50 characters, start with a letter, and contain only lowercase letters, numbers, and hyphens"400Invalid identifier format
"Agent with this identifier already exists"409Duplicate identifier within the project
"Cannot delete the default agent"400Attempting to delete the project’s default agent
"Agent is already the default"400Agent is already set as default
"Cannot use selective secret mode without assigned secrets"400Switching to selective mode with no secrets assigned
"One or more secrets not found"400Secret IDs in the request don’t exist in the project
"Agent not found"404Agent ID doesn’t exist

​
Secrets

Error messageStatusCause
"Enter a hostname, not a URL (remove http:// or https://)"400hostPattern includes a protocol prefix
"Enter a hostname only, not a path (use the path pattern field for paths)"400hostPattern includes a / path
"Host pattern must not contain spaces"400hostPattern contains whitespace
"At least one injection method (header/param) must be configured"400type is generic but injectionConfig is missing both headerName and paramName
"No fields to update"400PATCH request with an empty body
"Secret not found"404Secret ID doesn’t exist

​
Rules

Error messageStatusCause
"rateLimit and rateLimitWindow are required when action is rate_limit"400Action set to rate_limit without the required rate fields
"At least one field must be provided"400PATCH request with an empty body
"Policy rule not found"404Rule ID doesn’t exist

​
Apps

Error messageStatusCause
"Unknown provider: {provider}"404Provider name not in the app registry
"Provider \"{provider}\" is not available"400App exists but is not available for connection
"Missing fields in request body"400No fields object in connect request
"{field} is required"400A required credential field is empty
"connectionId query parameter is required"400Missing connectionId when disconnecting
"clientId is required"400BYOC config missing client ID
"clientSecret is required"400BYOC config missing client secret

​
User

Error messageStatusCause
"User name must be 1-255 characters"400Empty 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.
StatusRetryable?Notes
400NoFix the request body
401NoFix authentication
403NoCheck permissions
404NoFix the resource ID or path
409NoUse a different identifier
500YesRetry 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