willdady / api-conventions

API Response Conventions

The two keys

error carries a failure. message carries a 2xx status line for an
operation that has no resource to return.

return c.json({ error: "Workspace not found" }, 404);
return c.json({ message: "Board deleted" });

Never message on a 4xx/5xx — that is the one crossing the codebase does not
make.

A delete or action with nothing to return answers 200 { message } — never a
bodiless 204, and never { success: true }.

The error seam

Five cross-cutting failures are thrown, not returned. A single onError
seam maps each to its status and emits the same { error } body, so a domain
rule states its message once instead of once per caller:

A Postgres unique violation also maps to 409 — detect it through the shared
helper rather than re-reading the driver's error shape. So does a foreign-key
violation, as a backstop only: a delete guarded by a restrict reference
should throw a ConflictError naming what still uses the row first.

if (!row) throw new NotFoundError("Card not found");
throw new ValidationError("Invalid user assignee");

A resource referenced in the request body that isn't in this Organization, or
isn't Shared, is a NotFoundError (404) naming what couldn't be used — not a
422, and no extra detail fields beside error.

Throwing is what lets one rule serve more than one surface: the Kanban rules
answer both the HTTP routes and the Agent tool set from a single place. Reach
for the seam whenever the failure is one of those five; a 4xx that only one
route can produce still answers inline with c.json({ error }, status). Both
are current and roughly equally common — the seam is not a migration you
should finish.

Test assertions

Assert against the key the response actually uses:

expect(body.error).toBe("Invalid user assignee");
expect(await res.json()).toEqual({ message: "Board deleted" });

A service test covering a thrown failure asserts the error, not a body:

await expect(fn()).rejects.toThrow(NotFoundError);