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.
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. |