All errors use the envelope { "error": { "code": "...", "message": "..." } }. Policy/runtime errors may include a data field with evaluation context.
Auth & infrastructure
| Code | Status | Description |
|---|
| unauthorized | 401 | Missing or invalid API key |
| forbidden | 403 | Insufficient permissions |
| configuration_error | 500 | Server configuration error |
| rate_limit_exceeded | 429 | Request rate limit exceeded |
| rate_limit_unavailable | 503 | Rate limit backend unavailable |
CRUD & validation
| Code | Status | Description |
|---|
| invalid_request | 400 | Invalid parameters or malformed body |
| not_found | 404 | Resource does not exist |
| conflict | 409 | Resource conflict (e.g. duplicate slug) |
| query_failed | 400/500 | Database query failure |
| create_failed | 400/409 | Resource creation failed |
| update_failed | 400 | Resource update failed |
| delete_failed | 400 | Resource deletion failed |
| insert_failed | 400 | Record insertion failed |
Agent & policy runtime
| Code | Status | Description |
|---|
| agent_not_found | 403 | Agent identity not found in workspace |
| agent_context_required | 400 | Agent identity required by settings or policies |
| agent_identity_mismatch | 400 | Conflicting agent fields in input |
| agent_inactive | 403 | Agent is not active |
| agent_key_required | 401 | X-KorClaw-Agent-Key header missing |
| invalid_agent_key | 401 | Agent key does not match stored hash |
| environment_mismatch | 400 | Input environment does not match agent |
| environment_context_required | 400 | Environment required for scoped policies |
| evaluation_failed | 400 | Policy evaluation query failure |
| execution_proxy_required | 403 | Must use /runtime/execute for this action |
| policy_evaluation_required | 400 | POST /audit rejected allowed result |
| audit_persist_failed | 503 | Audit write failed after allowed evaluation |
Execution & MCP
| Code | Status | Description |
|---|
| invalid_execution_mode | 400 | Unknown execution mode |
| invalid_execution | 400 | Invalid execution block |
| invalid_execution_url | 400 | URL failed SSRF validation |
| execution_target_denied | 403 | Resource/tool not in agent allowlist |
| mcp_server_not_found | 404 | MCP server slug/ID not found |
| execution_failed | 502 | HTTP proxy execution failed |
| session_failed | 502 | MCP session creation failed |
| discovery_failed | 502 | MCP tool discovery failed |
| call_failed | 502 | MCP tool call failed |
Approvals
| Code | Status | Description |
|---|
| approval_decision_failed | 400/403/404/409 | Approval decision error |
| self_approval_forbidden | 403 | Cannot approve own request |
