It's easy to look at Next.js Server Actions and forget that they are, effectively, public API endpoints. The "magic" abstraction layer often tricks us into skipping standard backend best practices like validation and security.

But under the hood, Server Actions are still triggered by standard HTTP requests, meaning they are just as vulnerable to spam and abuse as any other route. If you have an action that is computationally expensive or costs money (like an AI call), you need to protect it.

Here is how to properly rate-limit your Server Actions to keep your application resilient.

---

Rate-limiting based on User ID

Rate-limiting requires a unique identifier for the incoming request. If you are dealing with authenticated users, this is straightforward: use their database ID.

Here's how you might handle this in a standard API route:

// API route (simplified):
export const POST = async () => {
  const user = await auth();
  // "rateLimiter" is a placeholder for your library of choice (e.g., Upstash, Redis)
  const { success } = await rateLimiter.limit(`subscription:${user.id}`);
  if (!success) {
    return new Response("Rate limited", { status: 429 });
  }
  return Response.json(await someExpensiveOperation());
};

When you move to Server Actions, the logic remains almost identical. The main difference is that instead of returning a 429 status code, you return a structured error object.

// Server Action (simplified):
export const action = async () => {
  const user = await auth();
  const { success } = await rateLimiter.limit(`subscription:${user.id}`);
  if (!success) {
    return {
      error: "You are doing that too much. Please try again later.",
    };
  }
  return someExpensiveOperation();
};

---

Rate-limiting based on IP address

Things get trickier when you need to rate-limit anonymous users (e.g., a public waitlist form or a "contact us" message). Since there is no user ID, the only reliable identifier is the IP address.

In a standard API route, you have direct access to the Request object that you can use to extract the IP address from the request headers.

// API route:
export const POST = async (req: NextApiRequest) => {
  const ip = getIP(req);
  const { success } = await rateLimiter.limit(`subscription:${ip}`);
  if (!success) {
    return new Response("Rate limited", { status: 429 });
  }
  return Response.json(await someExpensiveOperation());
};

For context, getIP is a small helper that looks at the x-forwarded-for header:

export function getIP(request: Request) {
  const xff = request.headers.get("x-forwarded-for");
  return xff ? xff.split(",")[0] : "127.0.0.1";
}

The Server Action problem

Let's try the same in a server action. Just extract the IP address from the request head... Hold on, we don't have a request object in a server action.

By design, Next.js Server Actions do not expose the raw Request object. However, we can work around this using the headers() function provided by next/headers. This gives us read-only access to the request headers associated with the current incoming request.

export const action = async () => {
  const headerList = await headers();
  const ip = (headerList.get("x-forwarded-for") ?? "127.0.0.1").split(",")[0];
  const { success } = await rateLimiter.limit(`subscription:${ip}`);
  if (!success) {
    return {
      error: "Too many requests.",
    };
  }
  return someExpensiveOperation();
};

By accessing the IP address through the headers() function, we effectively work around the limitation of not having a request object in Server Actions and can apply rate-limiting just as we would in a standard API route.

Bonus

To make things spicy, we can create a custom rate limiter function that we can invoke in each route and return specific data based on the number of requests. Here is my custom rate-limiter function that takes params and returns whether the user is blacklisted or not:

const rateLimitMap = new Map<
  string,
  { count: number; lastReset: number; suspendedUntil: number | null }
>();
const DEFAULT_LIMIT = 3;
const DEFAULT_WINDOW_MS = 60 * 1000;
const DEFAULT_SUSPENSION_MS = 5;
export function rateLimitByIp(
  ip?: string | null,
  options?: {
    limit?: number;
    suspensionMinutes?: number;
  },
): {
  allowed: boolean;
  message?: string;
} {
  const limit = options?.limit ?? DEFAULT_LIMIT;
  const suspensionMinutes = options?.suspensionMinutes ?? DEFAULT_SUSPENSION_MS;
  const suspensionMs = (options?.suspensionMinutes ?? 5) * 60 * 1000;
  const suspensionLabel =
    suspensionMinutes === 1 ? "1 minute" : `${suspensionMinutes} minutes`;
  if (!ip || ip === "Unknown") {
    return {
      allowed: true,
      message: "IP not provided; skipping rate limit.",
    };
  }
  const now = Date.now();
  const ipData = rateLimitMap.get(ip) || {
    count: 0,
    lastReset: now,
    suspendedUntil: null,
  };
  if (ipData.suspendedUntil && now < ipData.suspendedUntil) {
    return {
      allowed: false,
      message: `Too many attempts. Try again after ${suspensionLabel}.`,
    };
  }
  if (now - ipData.lastReset > DEFAULT_WINDOW_MS) {
    ipData.count = 0;
    ipData.lastReset = now;
  }
  if (ipData.count >= limit) {
    ipData.suspendedUntil = now + suspensionMs;
    rateLimitMap.set(ip, ipData);
    return {
      allowed: false,
      message: `Too many attempts. Try again after ${suspensionLabel}.`,
    };
  }
  ipData.count += 1;
  rateLimitMap.set(ip, ipData);
  return { allowed: true };
}

This function requires the IP address when called, and therefore we must create a custom function that reads the headers and returns the client IP address.

"use server";
import { headers } from "next/headers";
// In development, real proxy headers don't exist so we just return localhost
const isDev = process.env.NODE_ENV === "development";
export async function getClientIP(): Promise<string> {
  if (isDev) return "127.0.0.1";
  const headersList = await headers();
  const ipHeaders = [
    "cf-connecting-ip",      // Cloudflare — most trustworthy if you use it
    "x-real-ip",             // Nginx
    "x-forwarded-for",       // Standard proxy header (may contain a list)
    "x-client-ip",
    "x-cluster-client-ip",
    "forwarded",
  ];
  for (const header of ipHeaders) {
    const value = headersList.get(header);
    if (!value) continue;
    // x-forwarded-for can be "client, proxy1, proxy2" — first is the real client
    const ip = value.split(",")[0].trim();
    if (ip && isValidIP(ip)) return ip;
  }
  return "unknown";
}
//validate the IP address result
function isValidIP(ip: string): boolean {
  if (!ip || ip.toLowerCase() === "unknown") return false;
  // IPv4
  const ipv4 = /^(\d{1,3}\.){3}\d{1,3}$/;
  // IPv6
  const ipv6 = /^[\da-f:]+$/i;
  return ipv4.test(ip) || ipv6.test(ip);
}