> ## 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 Error responses come in two shapes. Route-level validation errors return a flat `error` string: ```json theme={null} { "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`: ```json theme={null} { "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: ```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 ```