Problem
An agent recovers from a failure by reading the error. Most docs.plus errors do not say enough to recover from.
Measured: 148 sites return an ad-hoc c.json({ error: '...' }) against 58 that call the house fail(c, ...) helper. Ten of the ad-hoc sites sit in the core document controller, not in the email or admin corners that apps/hocuspocus.server/API.md:73 names.
A validation failure names no field. A well-formed body and a nonsense body both return the same thing:
{"success":false,"error":{"message":"Request validation failed","code":"VALIDATION_ERROR"}}A person opens API.md and squints. An agent cannot, so it retries the same wrong call.
What to do
Wire the house envelope across the ad-hoc sites, starting with the ten in apps/hocuspocus.server/src/api/controllers/documents.controller.ts.
Make each validation failure name the field that failed and the next step.
Acceptance
Notes
This is a gate, not tidiness. Connector directory review rejects a generic error, and requires every tool to return a successful response for valid parameters.
The 429 path already does this correctly. It uses the house envelope and sets Retry-After, and it is the one error an agent can handle today.
Scope this to the tool-reachable surface. A full sweep of all 148 sites is a separate job.
Problem
An agent recovers from a failure by reading the error. Most docs.plus errors do not say enough to recover from.
Measured: 148 sites return an ad-hoc
c.json({ error: '...' })against 58 that call the housefail(c, ...)helper. Ten of the ad-hoc sites sit in the core document controller, not in the email or admin corners thatapps/hocuspocus.server/API.md:73names.A validation failure names no field. A well-formed body and a nonsense body both return the same thing:
{"success":false,"error":{"message":"Request validation failed","code":"VALIDATION_ERROR"}}A person opens
API.mdand squints. An agent cannot, so it retries the same wrong call.What to do
Wire the house envelope across the ad-hoc sites, starting with the ten in
apps/hocuspocus.server/src/api/controllers/documents.controller.ts.Make each validation failure name the field that failed and the next step.
Acceptance
code.Expected a file in the 'documentFile' field.Notes
This is a gate, not tidiness. Connector directory review rejects a generic error, and requires every tool to return a successful response for valid parameters.
The
429path already does this correctly. It uses the house envelope and setsRetry-After, and it is the one error an agent can handle today.Scope this to the tool-reachable surface. A full sweep of all 148 sites is a separate job.