Your API Is Making AI Agents Dumber (Fix It With Error Classification)

Most APIs return flat errors that mix fundamentally different failure modes. An agent cannot route to the right recovery strategy without parsing natural language error messages. Here is a fix. The Problem AI agents call your API with wrong parameters. They retry the same bad request three times, burn credits, and leave. From their logs it looks like your API failed. From yours it looks like the agent never questioned its own inputs. The default API contract is: send request, get success or failure. The agent learns nothing about WHY it failed. The Fix: correction_class Every error response should include a machine-readable correction_class field. One enum value that tells the agent what kind of recovery to attempt: 1. local_repair Parameter is malformed. Wrong format, typo, missing field. The agent can retry immediately with corrected input. { "error" : "invalid_captcha_type" , "correction_class" : "local_repair" , "correction_reason" : "Type 'recaptchav2' is not valid. Use: cloudflar