Explicit 501 Not Implemented responses are justified

An HTTP 501 with no explanation tells clients the endpoint exists but does nothing, with no context on when it will. Integration partners file tickets, mobile apps cache the error, and monitoring treats the response as healthy because it is a valid status code. A 501 is legitimate when documented — // TODO(ISSUE-123): refunds require Stripe migration — but unjustified 501s are indistinguishable from a forgotten stub.

Either implement the handler or annotate the 501 with a specific feature reference, issue number, and target window, then return a structured error body so clients can parse the gap. Example at app/api/refunds/route.ts:

// TODO(ISSUE-123): refunds require Stripe migration — target Q2 2026
export async function DELETE() {
  return Response.json(
    { error: 'Refunds not yet supported', issue: 'ISSUE-123' },
    { status: 501 }
  )
}

• ID: ai-slop-half-finished.incomplete-impl.return-501-not-implemented

• Severity: low

• What to look for: Walk all API handler files. Count all responses with HTTP status 501 (Response.json({...}, { status: 501 }), NextResponse.json({...}, { status: 501 }), res.status(501), new Response(..., { status: 501 })). For each occurrence, check whether a comment above or next to it provides a specific reason (at least 10 characters of justification mentioning the feature name).

• Pass criteria: 0 unjustified HTTP 501 responses in API handlers. Justified 501s (with clear comment explaining which feature is pending) are acceptable. Report: "Scanned X API handlers, found Y 501 responses, 0 are unjustified."

• Fail criteria: At least 1 HTTP 501 response with no justification comment.

• Skip (N/A) when: Project has 0 API handler files.

• Detail on fail: "1 unjustified 501: app/api/refunds/route.ts DELETE handler returns Response.json({}, { status: 501 }) with no comment. If this endpoint isn't ready, remove it or document the plan."

• Remediation: An unjustified 501 response tells clients "this feature doesn't exist" without explaining when it will. Either implement the handler or document the plan clearly:

  // Bad: silent 501 with no context
  export async function DELETE() {
    return Response.json({}, { status: 501 })
  }
  
  // Better: at least document it
  // TODO(ISSUE-123): refunds require Stripe migration — target Q2 2026
  export async function DELETE() {
    return Response.json(
      { error: 'Refunds not yet supported', issue: 'ISSUE-123' },
      { status: 501 }
    )
  }