Self-Reflective APIs: Structure Beats Verbosity for AI Agent Recovery
For developers building AI agents that interact with APIs, this work provides a practical method to improve agent recovery from errors, though the effect is model-dependent and the novelty is incremental.
Self-reflective APIs that return structured machine-readable suggestions on validation failure improve AI agent task-completion rates by 36.7–40.0 percentage points over plain-English error messages on Anthropic models, with 1.8–2.2× better per-success token efficiency, but the improvement is not significant on GPT-4o-mini.
When an AI agent calls an API and hits a validation error, it needs more than what went wrong -- it needs what to do next. A self-reflective API returns, on validation failure, a machine-readable recovery\_feedback.suggestions[] payload sufficient for the agent to repair the request and retry without external reasoning. On a leak-audited pilot ($N{=}30$ per cell, 3 LLMs, 10 adversarial tasks), structured suggestions lift task-completion rate by $+36.7$--$40.0$pp over plain-English diagnoses on Anthropic models (Fisher's exact $p \le 0.0022$), at $1.8$--$2.2\times$ better per-success token efficiency. The lift is not significant on gpt-4o-mini ($p{=}0.435$); a second-domain replication on a billing API confirms the pattern. The comparison only holds after auditing two undocumented classes of answer leakage in LLM benchmarks. We shipaudit\_prompt\_leakage.py as reusable CI infrastructure. Code and data: https://github.com/arquicanedo/self-reflective-apis.