Consistent response envelope format
Why it matters
Inconsistent response envelopes — some routes returning { data: ... }, others returning raw objects, others using { success: true, result: ... } — force every API consumer to write bespoke error-handling logic per endpoint. This violates ISO-25010:2011 compatibility.interoperability and means a new integration can silently swallow errors that use the wrong shape. In practice, it produces bugs where a frontend assumes data is present but the route returned the payload at root level.
Severity rationale
Medium because envelope inconsistency causes integration bugs and broken error handling but does not directly enable data exfiltration or service disruption.
Remediation
Define a shared response helper at src/lib/api-response.ts and replace all direct Response.json() calls with it:
// src/lib/api-response.ts
export const apiSuccess = <T>(data: T, status = 200) =>
Response.json({ data }, { status })
export const apiError = (code: string, message: string, status: number) =>
Response.json({ error: { code, message } }, { status })
Success responses always carry { data: <payload> }; error responses always carry { error: { code, message } }. Import and use these in every route handler. This gives clients a single shape to handle and gives you a single place to add observability later.
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the API Design Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · compatibility.interoperability — Interoperability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from saas-api-design·automated