{
  "instruction": "Return structured, consistent error responses from all Route Handlers with appropriate status codes",
  "relevant_when": "Agent creates or modifies Next.js Route Handlers (app/api/*/route.ts)",
  "context": "Route Handlers must return NextResponse.json() with a consistent error shape like { error: { code, message } } and explicit HTTP status codes. Unlike Express, Route Handlers return Response objects rather than mutating a res object. Common mistakes: forgetting to set status (defaults to 200), returning raw error strings, leaking stack traces, not wrapping request.json() in try/catch (it throws on invalid JSON), and inconsistent error formats across routes.",
  "sources": [
    {
      "type": "file",
      "filename": "skills/nextjs-api-patterns/SKILL.md",
      "tile": "tessl-labs/nextjs-api-patterns@0.2.0"
    }
  ],
  "checklist": [
    {
      "name": "structured-error-shape",
      "rule": "All error responses use a consistent object shape with at least a code field and a message field (e.g. { error: { code, message } }) -- not a mix of { error: 'string' }, { message: '...' }, or bare strings",
      "relevant_when": "Agent returns error responses from Route Handlers"
    },
    {
      "name": "explicit-status-codes",
      "rule": "Error responses include explicit HTTP status codes via NextResponse.json({...}, { status: 400 }) -- 400 for validation, 401 for auth, 404 for not found, 500 for internal errors -- never returning errors with a 200 status",
      "relevant_when": "Agent returns error responses from Route Handlers"
    },
    {
      "name": "request-json-try-catch",
      "rule": "Calls to request.json() in POST/PUT/PATCH handlers are wrapped in try/catch to handle malformed JSON, returning a 400 error instead of crashing",
      "relevant_when": "Agent writes Route Handlers that parse JSON request bodies"
    },
    {
      "name": "no-internal-error-leaks",
      "rule": "Unexpected errors (database failures, external service errors) return a generic message like 'An unexpected error occurred' -- no stack traces, file paths, or raw library errors in the response",
      "relevant_when": "Agent handles unexpected errors in Route Handlers"
    }
  ]
}