KorClaw returns errors in a consistent envelope: { "error": { "code": "...", "message": "..." } }. Branch on code, not message text.
Authentication errors
| Code | Status | Resolution |
|---|
| unauthorized | 401 | Check Authorization header format: Bearer kc_live_... |
| agent_key_required | 401 | Send X-KorClaw-Agent-Key — the agent has a key hash configured |
| invalid_agent_key | 401 | Verify the agent key matches what was set at registration |
| forbidden | 403 | API key lacks required permission for this endpoint |
Policy and agent errors
| Code | Status | Resolution |
|---|
| agent_not_found | 403 | Register the agent first or fix the agent identity in input |
| agent_inactive | 403 | Activate the agent (status: active) before evaluating |
| agent_context_required | 400 | Include agent identity — required by workspace setting or agent-scoped policies |
| environment_context_required | 400 | Include environment in input for environment-scoped policies |
| agent_identity_mismatch | 400 | Conflicting agent fields in input — use one consistent identifier |
| environment_mismatch | 400 | Input environment does not match the resolved agent environment |
| execution_proxy_required | 403 | Workspace requires execution through /runtime/execute, not evaluate-only |
Audit and rate limit errors
| Code | Status | Resolution |
|---|
| audit_persist_failed | 503 | Audit write failed after allowed evaluation — retry the request |
| rate_limit_exceeded | 429 | Slow down; honor Retry-After header |
| rate_limit_unavailable | 503 | Rate limit backend unavailable — retry with backoff |
| policy_evaluation_required | 400 | POST /audit rejects result: allowed — use /policy/evaluate instead |
