Documentation Index
Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
Use this file to discover all available pages before exploring further.
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.
All error responses return a JSON object with an error field:
{
"error": "Agent with this identifier already exists"
}
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
Agents
| Error message | Status | Cause |
|---|
"Agent name must be 1-255 characters" | 400 | Empty or overly long name field |
"Identifier must be 1-50 characters, start with a letter, and contain only lowercase letters, numbers, and hyphens" | 400 | Invalid identifier format |
"Agent with this identifier already exists" | 409 | Duplicate identifier within the project |
"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 |
"Cannot use selective secret mode without assigned secrets" | 400 | Switching to selective mode with no secrets assigned |
"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 |
"At least one injection method (header/param) must be configured" | 400 | type is generic but injectionConfig is missing both headerName and paramName |
"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 |
"At least one field must be provided" | 400 | PATCH request with an empty body |
"Policy rule not found" | 404 | Rule ID doesn’t exist |
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 |
"connectionId query parameter is required" | 400 | Missing connectionId when disconnecting |
"clientId is required" | 400 | BYOC config missing client ID |
"clientSecret is required" | 400 | BYOC config missing client secret |
User
| Error message | Status | Cause |
|---|
"User name must be 1-255 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 |
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
