Next.js API Route Tutorial: Validate, Rate Limit, Version

export async function POST(request: NextRequest) {
  const clientIp = getClientIp(request);
  const rateLimit = checkRateLimit(`contact:${clientIp}`, {
    limit: RATE_LIMIT,
    window: 60,
  });
  if (!rateLimit.success) {
    return rateLimited(RATE_LIMIT, rateLimit.resetIn);
  }

  let body: ContactBody;
  try {
    body = await request.json();
  } catch {
    return apiError({
      status: 400,
      code: "invalid_json",
      message: "Invalid JSON",
      hint: "Send a JSON object as the body, with Content-Type: application/json.",
    });
  }

The first two guards. The limiter runs before the body is read, and its key is the route name joined to the client address. The JSON parse sits in a try and catch so a broken body is a 400 with code invalid_json, not an unhandled exception.

  const clamp = (v: unknown, max: number): string =>
    typeof v === "string" ? v.trim().slice(0, max) : "";

  const name = clamp(body.name, 100);
  const email = clamp(body.email, 200);
  const intent = body.intent === "hr" ? "hr" : "project";
  const company = clamp(body.company, 120);
  const role = clamp(body.role, 120);
  const projectType = clamp(body.projectType, 80);
  const timeline = clamp(body.timeline, 80);
  const message = clamp(body.message, 5000);

  if (name.length < 2) {
    return apiError({
      status: 400,
      code: "invalid_request",
      message: "Please provide a valid name.",
      hint: "`name` must be 2 to 100 characters.",
    });
  }
  if (!EMAIL_RE.test(email)) {
    return apiError({
      status: 400,
      code: "invalid_request",
      message: "Please provide a valid email.",
      hint: "`email` must be a valid email address of at most 200 characters.",
    });
  }

Coerce, then check. clamp turns anything that is not a string into an empty string and cuts the rest to a maximum length, so the checks below only ever see short strings. Each hint names the field and its allowed range.

  try {
    const { error } = await getResend(apiKey).emails.send({
      from: fromEmail,
      to: toEmail,
      replyTo: email,
      template: {
        id: isHiring ? TEMPLATE_HIRING : TEMPLATE_PROJECT,
        variables,
      },
    });

    if (error) {
      console.error("Resend send error:", error);
      return apiError({
        status: 502,
        code: "upstream_error",
        message: "Failed to send message.",
        hint: "The email provider rejected the message. Retry later, or email matthewswong2610@gmail.com directly.",
      });
    }

    return NextResponse.json({ success: true });

The server-side call. The SDK returns an error instead of throwing, so the route checks it, logs the provider's detail on the server and answers 502 upstream_error with a generic message. A template id and variables replace an HTML body.

export function rateLimited(limit: number, resetIn: number): Response {
  return apiError({
    status: 429,
    code: "rate_limited",
    message: "Too many requests. Please try again later.",
    hint: `Wait ${resetIn} seconds before retrying; the limit is ${limit} requests per minute per client.`,
    retryAfter: resetIn,
    headers: {
      "Retry-After": String(resetIn),
      "X-RateLimit-Limit": String(limit),
      "X-RateLimit-Remaining": "0",
      "X-RateLimit-Reset": String(resetIn),
    },
  });
}

One helper builds the 429. Retry-After carries the wait in seconds, the X-RateLimit headers describe the window, and retryAfter repeats it in the body for clients that only read JSON. The hint tells a person what to do.

// Version 1 of the contact endpoint. The handler lives at app/api/contact,
// which stays as a deprecated, unversioned alias (see next.config.ts).
export { POST, GET, PUT, PATCH, DELETE } from "@/app/api/contact/route";

// Resend needs the Node.js runtime; segment config is never re-exported.
export const runtime = "nodejs";

The whole v1 endpoint. It re-exports every method from the original handler, so v1 and the deprecated alias can never diverge. It still declares the runtime itself; its own comment says segment config is never re-exported.

export const DEPRECATED_API_ALIASES = [
  { path: "/api/chat", successor: API_PATHS.chat },
  { path: "/api/chat/followups", successor: API_PATHS.followups },
  { path: "/api/contact", successor: API_PATHS.contact },
] as const;

The old paths as data. next.config.ts reads this list to stamp each alias with Deprecation and Link headers, and the developer guide and the OpenAPI description read the same list, so a deprecated path is declared once.

  // Fall back to the LAST X-Forwarded-For entry, not the first. Both Cloudflare
  // and nginx's $proxy_add_x_forwarded_for append, so the leftmost entry is
  // whatever the client chose to send: reading it let anyone mint a fresh
  // rate-limit bucket per request with `X-Forwarded-For: 1.2.3.<random>`, which
  // defeated every limit here — including the Groq spend and the Resend send
  // path. The rightmost entry is the one our own proxy wrote.
  const forwarded = request.headers.get("x-forwarded-for");
  if (forwarded) {
    const hops = forwarded
      .split(",")
      .map((hop) => hop.trim())
      .filter(Boolean);
    if (hops.length > 0) {
      return hops[hops.length - 1];
    }
  }

Which address is the client? The leftmost forwarded entry is whatever the caller sent, so the code reads the last one, written by the site's own proxy. The comment records the bug this replaced.