> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.v2.rasen.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.v2.rasen.ai/_mcp/server. # Error codes Each code has one HTTP status and one retry class. `details` holds only the fields listed here for the code. The spec's `x-error-catalog` is the public list; the status, retry class and message come from the public error registry locked by `CONTRACT.lock`. How to act on a code is described on [Errors](/concepts/errors). The catalog has 50 codes. | Code | HTTP | Retry | Public details | Message | Declared by | Note | | -------------------------------- | ---- | ------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `invalid_request` | 400 | `no` | `field`, `fields`, `allowed` | The request is not valid. | Every operation | | | `unauthenticated` | 401 | `no` | none | Authentication is required. | Every operation | | | `forbidden` | 403 | `no` | `required_role`, `required_capabilities` | This action is not permitted. | Every operation | The key lacks a capability. details.required\_capabilities lists every missing capability, including conditional ones. | | `not_found` | 404 | `no` | none | The resource was not found. | 85 operations | | | `agent_archived` | 409 | `no` | `agent_id` | The agent has been archived. | 28 operations | The agent is archived. Edits, validation, publication and rollback are refused. Call start uses agent\_not\_live with details.state=archived. | | `agent_name_taken` | 409 | `no` | `agent_id`, `name` | An agent already uses this name. | `createAgent`, `updateAgent` | | | `agent_not_assigned` | 409 | `no` | `agent_id` | The agent has no assigned checkpoint. | `createCall` | | | `agent_not_live` | 409 | `no` | `agent_id`, `state` | The agent is not live. | `addPhoneNumberOutboundAgent`, `createCall`, `setPhoneNumberInboundAgent` | | | `agent_not_published` | 409 | `no` | none | The agent has not been published. | 13 operations | | | `already_terminal` | 409 | `no` | none | The operation has already ended. | `admitCampaign`, `cancelCampaign`, `createCampaign`, `pauseCampaign`, `planCampaign`, `resumeCampaign`, `retryCampaign`, `startCampaign`, `suppressCampaignDestination`, `uploadCampaign` | The operation has already ended. | | `call_not_admittable` | 409 | `no` | `reasons` | The call cannot be admitted. | `createCall` | | | `carrier_action_required` | 409 | `no` | `carrier`, `capability` | The carrier needs a setup step. | `provisionPhoneNumber`, `removePhoneNumberInboundAgent`, `setPhoneNumberInboundAgent` | | | `carrier_capability_unsupported` | 409 | `no` | `carrier`, `capability` | The carrier does not support this. | `provisionPhoneNumber`, `setPhoneNumberInboundAgent` | | | `conflict` | 409 | `no` | `reason`, `current_live_version_id` | The request conflicts with the current state. | 38 operations | State conflict. details.reason (open vocabulary, listed per operation in x-conflict-reasons) says which recovery applies. | | `credential_unavailable` | 409 | `no` | none | The credential is unavailable. | 15 operations | | | `deletion_blocked` | 409 | `no` | `reason` | The item cannot be deleted while work is running or a hold applies. | `archiveKnowledgeSource`, `deleteKnowledgeSource`, `deleteSecret` | Deletion or removal is refused while a current reference or retention hold applies. details.reason is an open vocabulary listed per operation in x-deletion-reasons. For Knowledge, snapshot\_reference and published\_reference require retained content; archive the source instead. Legacy draft knowledge fields do not block Knowledge removal. Secret deletion remains refused while its draft or retained publication references exist, where draft\_reference still applies. | | `draft_conflict` | 409 | `no` | `expected_etag`, `current_etag`, `changed_at` | The draft has changed since it was read. | 13 operations | Stale revision on an agent, draft, variable, tool, MCP server or publication token. Re-read, re-apply your intended change and retry with the new ETag. Never blindly retry with a fresh ETag. details.expected\_etag is the If-Match you sent and details.current\_etag is the current ETag, both opaque strings. A publication-token mismatch uses the same shape, even when only a bound tool, MCP server, secret version or direct-library source changed. | | `idempotency_in_progress` | 409 | `retry_after` | none | The same request is still in progress. | 52 operations | The same intent is still running. Wait for Retry-After, then resend the identical request with the same key and original If-Match. | | `idempotency_key_expired` | 409 | `no` | `idempotency_key` | The idempotency key has expired. | 52 operations | | | `idempotency_key_reused` | 409 | `no` | `idempotency_key`, `operation`, `original_result_kind`, `original_state` | The idempotency key was used for a different request. | 52 operations | This key was used for a different request. Fix the caller; never retry a changed intent with the old key. | | `idempotency_result_gone` | 409 | `no` | `idempotency_key`, `operation`, `result_kind`, `result_ref` | The original result is no longer available. | 52 operations | | | `inbound_claimed_elsewhere` | 409 | `no` | none | This number already answers inbound calls in another workspace. | Not declared by a single operation | | | `knowledge_snapshot_unavailable` | 409 | `no` | `snapshot_id` | The knowledge index is not available. | `publishAgent`, `updateAgentDraft`, `validateAgentDraft` | | | `mcp_auth_mode_unsupported` | 409 | `no` | `mode`, `supported` | This authentication mode is not supported. | `createMcpServer`, `discoverMcpTools`, `replaceMcpServer` | | | `mcp_schema_drift` | 409 | `no` | `tool`, `kind` | The remote server no longer matches the published tools. | `createAgentTool`, `publishAgent`, `replaceAgentTool`, `validateAgentTool` | | | `mcp_tool_not_allowed` | 409 | `no` | `tool` | The tool is not on the allowlist. | `createAgentTool`, `replaceAgentTool`, `validateAgentTool` | | | `no_ready_placement` | 409 | `no` | `modality`, `fallback_mode` | There is no ready placement. | `createCall` | | | `no_recipients` | 409 | `no` | none | There are no recipients. | `admitCampaign`, `cancelCampaign`, `createCampaign`, `pauseCampaign`, `planCampaign`, `resumeCampaign`, `retryCampaign`, `startCampaign`, `suppressCampaignDestination`, `uploadCampaign` | There are no recipients. | | `not_dialing` | 409 | `no` | none | The campaign is not dialing. | `admitCampaign`, `cancelCampaign`, `createCampaign`, `pauseCampaign`, `planCampaign`, `resumeCampaign`, `retryCampaign`, `startCampaign`, `suppressCampaignDestination`, `uploadCampaign` | The campaign is not dialing. | | `not_draft` | 409 | `no` | none | The resource is not a draft. | `admitCampaign`, `cancelCampaign`, `createCampaign`, `pauseCampaign`, `planCampaign`, `resumeCampaign`, `retryCampaign`, `startCampaign`, `suppressCampaignDestination`, `uploadCampaign` | The resource is not a draft. | | `not_paused` | 409 | `no` | `state` | The campaign is not paused. | `admitCampaign`, `cancelCampaign`, `createCampaign`, `pauseCampaign`, `planCampaign`, `resumeCampaign`, `retryCampaign`, `startCampaign`, `suppressCampaignDestination`, `uploadCampaign` | The campaign is not paused. | | `not_planned` | 409 | `no` | none | The operation has not been planned. | `admitCampaign`, `cancelCampaign`, `createCampaign`, `pauseCampaign`, `planCampaign`, `resumeCampaign`, `retryCampaign`, `startCampaign`, `suppressCampaignDestination`, `uploadCampaign` | The operation has not been planned. | | `number_in_use` | 409 | `no` | `reason` | The number is still in use. | `removeImportedPhoneNumber` | | | `number_not_outbound` | 409 | `no` | none | The number does not support outbound calls. | `addPhoneNumberOutboundAgent`, `admitCampaign`, `cancelCampaign`, `createCall`, `createCampaign`, `pauseCampaign`, `planCampaign`, `resumeCampaign`, `retryCampaign`, `startCampaign`, `suppressCampaignDestination`, `uploadCampaign` | | | `provider_account_exists` | 409 | `no` | none | The provider account already exists. | `createTelephonyConnection`, `deleteTelephonyConnection`, `importPhoneNumbers`, `removeImportedPhoneNumber`, `replaceTelephonyConnection` | | | `resource_key_conflict` | 409 | `no` | `existing_id`, `resource_type` | A resource with this resource key already exists. | `createAgent`, `createAgentKnowledgeSource`, `createAgentTool`, `createKnowledgeSource`, `createMcpServer`, `createSecret`, `replaceAgentTool`, `replaceMcpServer`, `uploadAgentKnowledgeSource`, `uploadKnowledgeSource` | A resource of this type already has this resource\_key. details.existing\_id identifies it; read it and reconcile. details.resource\_type is one of agent, mcp\_server, knowledge\_source or secret (open vocabulary). | | `telephony_not_connected` | 409 | `no` | `mode` | Telephony is not connected. | 16 operations | | | `tool_name_conflict` | 409 | `no` | `name`, `count` | Two tools use the same name. | `createAgentTool`, `replaceAgentTool`, `validateAgentTool` | | | `workspace_unavailable` | 409 | `no` | none | The workspace is unavailable. | 55 operations | | | `payload_too_large` | 413 | `no` | `bytes`, `limit_bytes` | The payload exceeds the size limit. | 37 operations | | | `unsupported_media_type` | 415 | `no` | `content_type`, `expected` | The media type is not supported. | `admitCampaign`, `cancelCampaign`, `createCampaign`, `pauseCampaign`, `planCampaign`, `resumeCampaign`, `retryCampaign`, `startCampaign`, `suppressCampaignDestination`, `uploadAgentKnowledgeSource`, `uploadCampaign`, `uploadKnowledgeSource` | | | `outbound_destination_refused` | 422 | `no` | none | The destination is not permitted. | 18 operations | | | `revision_required` | 428 | `no` | `header` | The request requires a revision. | 34 operations | | | `quota_exceeded` | 429 | `retry_after` | `meter`, `period`, `period_end`, `limit`, `used`, `requested`, `available`, `unit` | The quota has been exceeded. | Every operation | | | `rate_limited` | 429 | `retry_after` | `limit`, `scope`, `window_s` | The request rate limit has been reached. | Every operation | | | `internal_error` | 500 | `yes` | `request_id` | The request could not be completed. | Every operation | For an operation that takes an Idempotency-Key, a client retry with the same key is safe: the server replays the stored outcome if the first attempt took effect; if the first attempt had no effect, the retry performs the operation once. Never retry with a new key. | | `provider_unavailable` | 502 | `no` | none | The provider is unavailable. | `createCall`, `createTelephonyConnection`, `deleteTelephonyConnection`, `endCall`, `importPhoneNumbers`, `listAvailablePhoneNumbers`, `provisionPhoneNumber`, `removeImportedPhoneNumber`, `removePhoneNumberInboundAgent`, `replaceTelephonyConnection`, `setPhoneNumberInboundAgent` | For an operation that takes an Idempotency-Key, a client retry with the same key is safe: the server replays the stored outcome if the first attempt took effect; if the first attempt had no effect, the retry performs the operation once. Never retry with a new key. | | `at_capacity` | 503 | `retry_after` | `class`, `limit` | There is no capacity available. | Every operation | For an operation that takes an Idempotency-Key, a client retry with the same key is safe: the server replays the stored outcome if the first attempt took effect; if the first attempt had no effect, the retry performs the operation once. Never retry with a new key. | | `call_orchestrator_unavailable` | 503 | `retry_after` | none | No orchestrator answers. | Every operation | For an operation that takes an Idempotency-Key, a client retry with the same key is safe: the server replays the stored outcome if the first attempt took effect; if the first attempt had no effect, the retry performs the operation once. Never retry with a new key. | | `unavailable` | 503 | `retry_after` | `dependency` | The service is unavailable. | Every operation | For an operation that takes an Idempotency-Key, a client retry with the same key is safe: the server replays the stored outcome if the first attempt took effect; if the first attempt had no effect, the retry performs the operation once. Never retry with a new key. |