# No stub return values in non-trivial handlers

- **Pattern:** `ab-000259` (`ai-slop-half-finished.mock-responses.stub-return-values`)
- **Severity:** medium
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000259
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000259)

## Why it matters

A handler whose body is only `return Response.json({})` or `return new Response()` returns HTTP 200 without doing anything. The client accepts it as success, moves on, and logs no error. Orders never save, refunds never queue, webhooks never acknowledge — and the failure is invisible until a customer complains or a reconciliation job runs weeks later. This pattern ships constantly when AI scaffolds a route file it never finishes wiring.

## Severity rationale

Medium because silent success on a non-health endpoint causes data loss without producing any observable error.

## Remediation

Either implement the handler against the real data source or return an explicit `501 Not Implemented` so clients see the gap. Never leave a stub that returns 200. Example at `app/api/orders/route.ts`:

```ts
export async function POST(req: Request) {
  const order = await prisma.order.create({ data: await req.json() })
  return Response.json(order, { status: 201 })
}
```

## Detection

- **ID:** `stub-return-values`
- **Severity:** `medium`
- **What to look for:** Walk all API handler files. Count all HTTP method handler function bodies where the body contains ONLY one of these stub returns: `return;`, `return null;`, `return undefined;`, `return Response.json({});`, `return Response.json(null);`, `return Response.json([]);`, `return NextResponse.json({});`, `return new Response();`, `return new Response(null);`. EXCLUDE routes whose path contains `health`, `healthz`, `ping`, `ready`, `status` (legitimate empty responses). EXCLUDE routes that also contain comments explicitly justifying the empty return.
- **Pass criteria:** 0 non-health-check API handlers return only stub values. Report: "Scanned X API handlers (excluding Y health-check routes), 0 return stub-only values."
- **Fail criteria:** At least 1 non-health-check API handler has a body consisting only of a stub return.
- **Skip (N/A) when:** Project has 0 API handler files.
- **Detail on fail:** `"2 handlers with stub-only returns: app/api/orders/route.ts POST handler body is 'return Response.json({})', app/api/refunds/route.ts DELETE handler body is 'return new Response()'"`
- **Remediation:** A handler that only returns `{}` or `null` tells the client the request succeeded but does nothing — which is worse than failing loudly. Either implement the logic or return a proper HTTP error:

  ```ts
  // Bad: silently does nothing
  export async function POST() {
    return Response.json({})
  }

  // Good: return 501 Not Implemented explicitly
  export async function POST() {
    return Response.json(
      { error: 'Not yet implemented' },
      { status: 501 }
    )
  }

  // Better: implement the handler
  export async function POST(req: Request) {
    const order = await prisma.order.create({ data: await req.json() })
    return Response.json(order, { status: 201 })
  }
  ```

---

Taxons: placeholder-hygiene

HTML version: https://auditbuffet.com/patterns/ab-000259