Error Glossary

{
  "error": {
    "type": "permission_error",
    "code": "blocked_by_policy",
    "message": "Action blocked by governance policy",
    "hint": "Resolve the escalation or adjust governance rules",
    "doc_url": "https://accomplishanything.today/infra/docs/errors#err-blocked_by_policy",
    "next_action": {
      "type": "resolve_escalation",
      "label": "Resolve the policy block"
    }
  }
}

Every error response includes a trace_id. Use it to inspect the full context in the dashboard trace explorer.

Outcome vs. Error

Not every non-200 response is an error. Some 2xx responses carry a structured status:

Branch on status or type, never on the HTTP status alone. The X-Cadreen-Gate header mirrors the gate: ok, blocked, escalate, needs_input.

Error catalog

Every error code Cadreen returns. The hint field on each error response tells you how to fix it. Bookmark this page — it is the canonical error reference.

Authentication & rate limit errors

These errors occur when your API key is missing, invalid, or you are sending too many requests.

Recovery & self-healing

For tool failures and execution errors, Cadreen has a self-healing subsystem that diagnoses root causes and records recoveries:

• POST /api/v1/cadreen/healing/diagnose — Diagnose a failure by error message, category, and tool name. Returns root cause, confidence, and recovery strategy.
• GET /api/v1/cadreen/healing/precedents — Browse past recoveries to find a pattern that matches your failure.

What not to do

Common integration mistakes and how to avoid them.

• 1Do not parse prose to decide what happened. Always branch on type, status, or gate.reason_code. Message content strings may change phrasing.
• 2Do not ignore governance gates. The X-Cadreen-Gate header says blocked — the action did not execute. Do not retry without resolving the gate first.
• 3Do not retry blindly. Check the gate and next_action first. Retries without resolving the root cause are wasted calls and will hit the same block.
• 4Do not store secrets in memory items. Use POST /api/v1/cadreen/credentials for API keys, tokens, and secrets. Memory items are queryable and shareable — credentials are encrypted at rest and never surfaced in traces.
• 5Do not treat intelligence.process.duration_ms as SLA. It varies with model latency and system load. Use X-Cadreen-Trace-ID for observability, not timing contracts.
• 6Do not hard-code field paths inside intelligence. Use the field_stability.stable list to know what is safe to depend on. Fields in evolving may change.
• 7Do not discard the setup response. POST /api/v1/cadreen/setup returns your installation checklist: connections to register, memory to upload, policies to confirm, and webhooks to configure. Revisit it as your integration grows.