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.

翻译：当AI智能体调用API并遇到验证错误时，其所需的不仅是错误原因——更需要后续操作指引。自省式API在验证失败时返回包含机器可读的`recovery_feedback.suggestions[]`负载，该负载足以让智能体修复请求并重新执行，无需外部推理。在经泄露审计的试点实验（每单元$N{=}30$，3个LLM，10个对抗性任务）中，结构化建议使Anthropic模型的任务完成率相比纯文本诊断提升$+36.7$--$40.0$个百分点（Fisher精确检验$p \le 0.0022$），每次成功token效率提升$1.8$--$2.2$倍。但在gpt-4o-mini上提升不显著（$p{=}0.435$）；在计费API上的第二领域复现验证了该模式。该比较仅在审计LLM基准测试中两类未记录的回答泄露后成立。我们发布`audit_prompt_leakage.py`作为可复用CI基础设施。代码与数据：https://github.com/arquicanedo/self-reflective-apis。