Errors

The Errors view aggregates failures from all your agent traces into a structured error log. Instead of hunting through individual traces, you see errors grouped by type and agent so you can triage at scale. In the sidebar, this page is the Errors tab of the Issues row (in Fix). See Finding your way around the dashboard.

​

Error types

Zespan classifies errors into four categories:

​

Changes on the error timeline

The stacked error chart shows the changes on your change timeline (a deploy reported from CI, a prompt version, a config or policy edit) as dashed markers on the bucket they happened in, so a jump in errors can be read against what changed just before it. The Changes button above the chart hides or shows them.

​

How errors are classified

The Errors page, the error-rate alert metrics, and the performance error rates all use one rule. A call counts as an error when its status is error or rate_limited, or when it has an error_code. The error code decides the type first, then the status:

• Timeout — timeout or 408
• Rate limit — rate_limited, rate_limit, rate_limit_exceeded, or 429, or a rate_limited status with no code
• Content filter — content_filter or content_policy
• Guardrail blocked — guardrail_blocked
• Tool error — tool_error, any code starting with tool_ (such as tool_timeout or tool_http_503), validation_error (a tool’s arguments failed validation), or a tool span that failed with no code
• Other — everything else

Errors with no error_code are no longer dropped from the groups. They are grouped under the code unknown, or rate_limited when only the status said so, so group totals add up to the total error count. The error timeline has an other series for errors that fit none of the named types, so its series add up to total_errors too. Rate limit and timeout are checked first, so rate_limit_exceeded is a rate limit and plain timeout stays a timeout, even on a tool span. The rate-limit heatmap and the error rate by model use the same rule. The by-model table lists models with more than 10 calls in the period.

​

Errors by agent and tool

Errors are attributed to an agent per trace. An error on an LLM span that has no agent name of its own counts toward the most frequent named agent in the same trace, so the by-agent error counts match the error counts on the Agents list. Counts are distinct spans. On the API (GET /projects/{id}/errors, ranges 24h, 7d, 30d, 90d, each a trailing window):

​

Error list

The error list shows all errors in the selected time range, with:

• Error message (truncated to 200 characters)
• Error type
• Agent that produced the error
• Model (for model errors)
• Tool name (for tool errors)
• Timestamp and count (how many times this exact error occurred)

Errors with identical messages and sources are grouped automatically. A group showing 47 occurrences means the same error happened 47 times — not 47 unique bugs.

​

Filtering

Filter by error type, agent, model, environment, or date range. The Only new toggle shows only errors that first appeared in the selected period — useful for spotting regressions after a deployment.

​

Opening the source trace

Click any error row to open the trace that produced it. The flame graph highlights the failed span so you can see the full context — what the agent was doing when the error occurred, what inputs led to it, and what happened immediately before.

​

Error rate metrics

The error rate chart at the top of the page shows errors per hour over the selected period. A flat baseline with sudden spikes indicates an external event (provider outage, a bad deployment). A gradually increasing baseline indicates a growing problem.

​

Next steps

• Incidents — AI-detected anomalies, including error surges
• Alerts — set up notifications when error rates exceed a threshold
• Traces — investigate individual failed runs