> ## 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. # 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 All error responses return a JSON object with an `error` field: ```json theme={null} { "error": "Agent with this identifier already exists" } ``` For validation errors, the message is the first issue reported by the validator. ## 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 | For `500` errors, retry with exponential backoff: ```bash theme={null} # 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 ```