Error Taxonomy

Risicare classifies agent errors using a hierarchical taxonomy designed for AI systems. The taxonomy covers both single-agent failures (perception, reasoning, tool use, memory, output) and multi-agent failures (coordination, communication, orchestration, consensus, resources).

Taxonomy Structure

Module (10)
└── Category (31)
    └── Error Code (154)
        └── Format: MODULE.CATEGORY.CODE

Modules Overview

Quick Reference

Error Code Format

TOOL.EXECUTION.TIMEOUT
  │      │        │
  │      │        └── Code (specific error)
  │      └── Category (error type)
  └── Module (system area)

Severity Levels

Each error code has a severity from 1 to 5:

Using Error Codes

In the API

Two list endpoints filter by error code, and the filter is applied:

curl "https://app.risicare.ai/api/v1/diagnoses?error_code=TOOL.EXECUTION.TIMEOUT" \
  -H "Authorization: Bearer rsk-..."
 
curl "https://app.risicare.ai/api/v1/fixes?error_code=TOOL.EXECUTION.TIMEOUT" \
  -H "Authorization: Bearer rsk-..."

Exact matches only — there is no wildcard syntax, so TOOL.* matches nothing.

In Dashboards

The traces view filters on time window, errored-or-completed status, environment, and a free-text search box. That search matches the root span name and a trace-ID prefix only — typing an error code into it will not find traces carrying that code. There is no error-code filter control and no field:value search syntax.

In Alerts

Alert rules are metric-and-threshold, not per-error-code expressions. A rule names one metric, an operator, and a numeric threshold:

Operators are gt, lt, eq, gte, lte, ne. A rule naming any metric outside this list is skipped by the alert worker and logged as unsupported. You cannot alert on a specific error code today — error_rate counts all errors together.

In Fixes

Each fix targets exactly one error code, in the singular field target_error_code:

{
  "fix_type": "retry",
  "target_error_code": "TOOL.EXECUTION.TIMEOUT",
  "config": { "max_retries": 3, "initial_delay_ms": 1000, "exponential_base": 2.0 }
}

Next Steps

Select a module to see all its error codes: