Use Proper HTTP Status Codes

Why this matters

HTTP status codes are not just numbers — they drive behavior across the entire infrastructure stack:

• Monitoring/alerting: tools like Datadog and Sentry track 4xx/5xx rates. If errors return 200, they're invisible to monitoring.
• CDN/caching: CDNs cache 200 responses. A 200 error response gets cached and served to every subsequent user.
• Retry logic: clients retry 503 (Service Unavailable) but not 200. Wrong status codes break automatic recovery.
• API consumers: developers expect to check response.ok or the status code. A 200 with an error body forces them to parse the response to detect failures.

Using 200 for everything is the API equivalent of returning { success: true, error: "Something went wrong" } — technically valid, practically useless.

The rule

Return the most specific, semantically correct HTTP status code for every response:

Bad example

// BAD: 200 for everything
export async function POST(request: Request) {
  try {
    const body = await request.json();
    const user = await db.user.findUnique({ where: { id: body.id } });
 
    if (!user) {
      return Response.json({ error: "User not found" }); // 200!
    }
 
    return Response.json({ data: user }); // 200
  } catch (error) {
    return Response.json({ error: "Something went wrong" }); // 200!
  }
}

Good example

// GOOD: semantically correct status codes
export async function POST(request: Request) {
  try {
    const body = await request.json();
 
    if (!body.id) {
      return Response.json(
        { error: "Missing required field: id" },
        { status: 400 }
      );
    }
 
    const user = await db.user.findUnique({ where: { id: body.id } });
 
    if (!user) {
      return Response.json(
        { error: "User not found" },
        { status: 404 }
      );
    }
 
    return Response.json({ data: user }, { status: 200 });
  } catch (error) {
    console.error("Unexpected error:", error);
    return Response.json(
      { error: "Internal server error" },
      { status: 500 }
    );
  }
}

How to detect

Search for Response.json calls without explicit status codes:

grep -n "Response.json(" --include="*.ts" --include="*.tsx" -r app/api/

Any Response.json({ error: ... }) without a status parameter defaults to 200.

Remediation

1. Audit all API routes for Response.json calls that return errors with no status code
2. Add explicit status codes to every response: { status: 4xx } for client errors, { status: 5xx } for server errors
3. Create a response helper to standardize: errorResponse(status, message) and successResponse(data, status)
4. Verify monitoring dashboards track non-200 responses

References

• MDN: HTTP response status codes
• RFC 9110: HTTP Semantics — Status Codes
• REST API Design: Status Codes