Contents
Opening failures by type — the 108-failure breakdown
A report saying "the API didn't work" offers no clue on its own. What matters is what the agent tripped over. KanseiLink collects outcome reports tagged with an error_type. Here we took the five most-reported services — freee (212 reports), Slack (113), SmartHR (92), Backlog (91), kintone (61), 569 total — and pulled out only the failures, sorted by type. We could catalogue 108 failures. The breakdown:
| Error type | Count | Share of all failures | Nature |
|---|---|---|---|
| api_error (4xx/5xx bucket) | 75 | ~69% | Server-side, opaque |
| Auth (auth_expired / auth_error) | 15 | ~14% | Operational, partly self-fixable |
| search_miss (discovery failure) | 13 | ~12% | Discoverability, AEO-fixable |
| invalid_input | 3 | ~3% | Schema, self-fixable |
| timeout | 2 | ~2% | Load, avoidable via paging |
At a glance you'd want to conclude: "api_error is ~70%, so fix that." But this article argues the opposite. The largest bucket is not necessarily where the most fixable headroom lives. The smaller buckets are precisely where vendors have direct levers. Let's open them in turn.
The three big buckets of 108 failures
api_error — the largest, but most opaque failure
api_error bundles the 4xx/5xx responses the server returned. It is the biggest category at about 69% (75) of failures — and yet, from the agent's vantage point, it is the "I can't tell what went wrong" failure. When the response is just a "400 Bad Request" or a vague "500 Internal Server Error," the agent has no way to repair and hits the same wall on retry.
The trouble is that fixing this bucket depends almost entirely on the service provider. No matter how clever the agent, if the server doesn't return a cause it cannot self-correct. Conversely, simply embedding "which field, why, and how to fix it" in machine-readable form turns much of these 75 into "the next success." This is exactly the problem of error message quality.
api_error has the highest count, but agents can't self-solve it. The fix rests on vendor error design and has a long lead time. Anchoring on "70% of failures" and staring only here makes you miss cheaper, faster wins.
Expired auth — "expires every 24h" quietly bites
The second-largest bucket is auth (auth_expired + auth_error) at about 14% (15). The contents are telling. In freee's reports, the verified workaround for auth_expired appears repeatedly: "refreshed the OAuth token; the token expires every 24h." The cause isn't a design flaw — it's that the agent steps on the expiry spec without knowing it exists.
This is the classic "failure documentation could have prevented." Spell out token lifetime, refresh procedure, and expiry behavior in structured docs, and agents can schedule refreshes in advance — most auth_expired vanishes before it occurs. For SmartHR, the verified workaround for auth_expired is "use the v2 endpoint instead of v1," another you-don't-trip-if-you-know failure.
Auth errors aren't "the service is broken" — they are "the spec didn't reach the agent." Unlike api_error, you can reduce them with documentation alone, without changing a single line of code. High ROI, easily overlooked.
search_miss — the one failure vendors can fix directly
At about 12% (13) of failures, search_miss is fundamentally different in nature. It is a failure that happens before the API is even called — the agent could not discover a service matching its intent. The real examples are vivid:
- SmartHR: query "issue a withholding tax slip (源泉徴収票を発行したい)" → top 3 returns [freee, moneyforward, kingoftime], no SmartHR. "manage employee onboarding" also misses the top 3.
- kintone: "build a no-code internal request form (ノーコードで社内申請フォームを作りたい)" → returns [notion, backlog, chatwork], no kintone.
- freee: "streamline back-office work (バックオフィス業務を効率化)" → freee not in the top 3.
These have nothing to do with API quality. SmartHR and kintone are robust services, but if the agent never finds them as candidates, neither success nor failure occurs — or, more precisely, a quiet "was-never-discovered" failure piles up. And undiscovered services accumulate no track record, getting stranded in the long tail of usage concentration.
Whereas api_error and auth are server-implementation/operational issues, search_miss is a discoverability problem. Align your service description and metadata with the agent's intent language — not human-facing marketing copy — and you reduce it directly. This is precisely what AEO (Agent Engine Optimization) solves. That 12% is lost "before you're even used," and it's the easiest to recover.
Failures concentrate in one service — SmartHR is half
There's another fact the average hides: failures are not evenly spread. Of the 108 catalogued failures, SmartHR alone accounts for about 51% (55). For api_error specifically, 36 of all 75 — about 48% are SmartHR.
| Service | Reports | Success rate | Failures (approx.) | Main failure types |
|---|---|---|---|---|
| SmartHR | 92 | 39% | ~55 | api_error 36 / auth 10 / search_miss 7 |
| freee MCP | 212 | 90% | ~21 | api_error 15 / auth 4 |
| kintone MCP | 61 | 79% | ~13 | api_error 9 / search_miss 3 |
| Slack MCP | 113 | 91% | ~10 | api_error 9 |
| Backlog MCP | 91 | 90% | ~9 | api_error 6 / search_miss 2 |
SmartHR stays at a low 39% success rate yet is used frequently (92 reports). As Japan's HR SaaS market leader with few real substitutes, agents keep choosing it even as they fail — so its absolute failure count dominates. By contrast, Slack (91%), freee (90%), and Backlog (90%) keep absolute failures small despite high report volumes.
"70% of all failures are api_error" is correct at the top line, but nearly half of that breakdown traces to a single service. Failure mitigation must look not only at error type but at which service it occurs in. Improving one low-success-rate service can shift the entire failure distribution.
What vendors should prioritize
From dissecting these 108 failures, the priority order for providers is clear.
- Kill search_miss first (cheapest, fastest) — improve discoverability for intent keywords. No code change; just metadata and description tuning rescues the 12% lost as "pre-discovery losses."
- Document the auth spec — token lifetime, refresh procedure, expiry behavior, recommended endpoint (v1/v2). Much of the 14% auth bucket is "you don't trip if you know."
- Make errors machine-readable — api_error is the largest bucket, but embedding repair hints turns retries into successes. Stop "returning just a 400."
- Start with low-success-rate services — failures aren't even; they concentrate in one service. If you're on the low end of the long tail, lifting your success rate first is the global optimum.
FAQ
What is the most common error agents fail on?
Across 5 high-volume services (569 reports), of the 108 catalogued failures about 69% (75) were api_error, then auth ~14% (15), search_miss ~12% (13), invalid_input ~3%, timeout ~2%.
Why isn't api_error the "top priority" despite being largest?
api_error bundles opaque server-side 4xx/5xx failures; fixing it depends on vendor error design and has a long lead time. By contrast, search_miss and auth can be reduced with metadata and documentation alone, giving higher ROI.
What is search_miss and why does it matter for AEO?
A failure where the agent couldn't discover a service matching its intent — e.g., "issue a withholding tax slip" not surfacing SmartHR. It's a discoverability problem, not an API quality one, and is directly fixable by aligning descriptions and metadata with the agent's intent language (AEO).
Are failures concentrated in particular services?
Heavily. Of 108 failures, SmartHR alone is ~51% (55), and 36 of 75 api_errors (~48%) are SmartHR — because it stays at a low 39% success rate while being used frequently.
What should vendors prioritize from this failure data?
(1) Improve discoverability to kill search_miss, (2) document the auth spec (token lifetime, refresh, recommended endpoint), (3) make errors machine-readable. search_miss in particular is the highest-ROI area.
Figures are aggregated via get_insights from live outcome reports KanseiLink collected from agents (snapshots as of each service's last_updated in April 2026). Scope is the 5 most-reported services: freee MCP (212 reports / 90% success; errors api_error 15, auth_expired 4, timeout 1, search_miss 1), Slack MCP (113 / 91%; api_error 9, invalid_input 1), SmartHR (92 / 39%; api_error 36, auth_expired 10, search_miss 7, timeout 1, invalid_input 1), Backlog MCP (91 / 90%; api_error 6, search_miss 2, auth_error 1), kintone MCP (61 / 79%; api_error 9, search_miss 3, invalid_input 1). "108 failures" is the simple sum of these error_type reports, and each share (api_error ~69% = 75/108, auth ~14% = 15/108, search_miss ~12% = 13/108) is its ratio. Per-service failure counts are approximations from (reports × (1 − success rate)) and may differ from reported error_type counts by ~1. Report counts vary continuously with agent activity. The prioritization of error types is an analytical interpretation of observed data and does not guarantee any service's future quality. Verify current values via each get_insights.