This guide covers when to use Server Actions vs API Routes in Next.js 16 — with performance data, security differences, real TypeScript examples, and a decision framework you can apply to any feature. Key takeaways: - **One question decides it:** Is the caller your own React code, or something outside your app? Internal → Server Action. External → API Route. - Server Actions are faster for UI-driven mutations — Next.js optimizes the request/response cycle. API Routes outperform Server Actions in high-concurrency benchmarks. ([source](https://nextjsreactjs.com/latest-article/nextjs-server-actions/)) - Server Actions have a **1MB request body limit**. For file uploads or large payloads, use API Routes. - Next.js 16 ships `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` — encrypted action IDs that prevent replay attacks. Server Actions get CSRF protection automatically. API Routes do not. ([source](https://www.verlua.com/blog/server-actions-vs-api-routes)) - In Next.js 16, `params`, `cookies()`, and `headers()` must all be awaited. The codemod handles this automatically.

## The Core Difference Both Server Actions and API Routes run on the server. Both can read your database, call external APIs, and handle sensitive logic. The difference is not about what they do — it's about who calls them. **A Server Action is a function.** You import it and call it from a React component. Next.js handles the HTTP request behind the scenes. The caller is always your own React code. **An API Route is a URL.** It lives at `app/api/your-endpoint/route.ts` and responds to HTTP requests. Any client that can make an HTTP request can reach it — your React code, a Stripe webhook, a mobile app, a CLI script. That single distinction — function vs URL — drives every decision in this guide. | | **Server Actions** | **API Routes** | |---|---|---| | Called from | React components only | Any HTTP client | | HTTP method | POST only | GET, POST, PUT, DELETE, PATCH | | Type safety | Automatic — inferred from function signature | Manual — validate incoming JSON yourself | | Caching | Not cacheable | GET requests cacheable | | Progressive enhancement | Yes — works without JavaScript | No | | CSRF protection | Built in — framework-level | Must implement yourself | | Body size limit | 1MB default | Configurable | | External access | No | Yes | | Best for | Internal mutations from your UI | Webhooks, public APIs, mobile apps |

## What Changed in Next.js 16 Before the examples — if you're on Next.js 16, three things changed that affect how you write both patterns. **Async params in Route Handlers:** ```ts // Next.js 16 — params must be awaited export async function GET( request: NextRequest, { params }: { params: Promise<{ id: string }> } ) { const { id } = await params; // ... } ``` **Async `cookies()`, `headers()`, and `draftMode()` in Server Actions:** ```ts "use server"; import { cookies } from "next/headers"; export async function myAction() { const cookieStore = await cookies(); // must await in Next.js 16 const token = cookieStore.get("session")?.value; } ``` **`middleware.ts` renamed to `proxy.ts`:** If you use middleware for auth, rename `middleware.ts` → `proxy.ts` and rename the exported function from `middleware` → `proxy`. Run the codemod to migrate automatically: ```bash npx @next/codemod@canary upgrade latest ```

## Server Actions: The Pattern for Internal Mutations A Server Action is an async function marked `"use server"`. Next.js compiles it to a POST endpoint, but you never see the HTTP layer — you just call a function. ```ts // app/actions/posts.ts "use server"; import { revalidatePath } from "next/cache"; import { db } from "@/lib/db"; import { z } from "zod"; const schema = z.object({ title: z.string().min(1).max(200), content: z.string().min(1), }); export async function createPost(formData: FormData) { const result = schema.safeParse({ title: formData.get("title"), content: formData.get("content"), }); if (!result.success) { return { success: false, error: result.error.flatten().fieldErrors }; } await db.posts.create({ data: result.data }); revalidatePath("/posts"); return { success: true }; } ``` Use `useActionState` (React 19 — replaces the older `useFormState`) to handle the response and pending state in a Client Component: ```tsx // app/posts/new/page.tsx "use client"; import { useActionState } from "react"; import { createPost } from "@/app/actions/posts"; export default function NewPostPage() { const [state, action, isPending] = useActionState(createPost, null); return (

{state?.error && (
        <p className="text-red-500">{JSON.stringify(state.error)}</p>
      )}
      <button type="submit" disabled={isPending}>
        {isPending ? "Creating..." : "Create post"}
      </button>
    </form>
  );
}
```

**Where Server Actions genuinely win:** Form submissions, button-triggered mutations, any create/update/delete operation your own UI initiates. The zero-boilerplate model — no fetch, no request/response, automatic type safety — makes common paths much simpler.

**Where Server Actions hit limits:**
- POST only — can't be used for cacheable GET requests
- 1MB body limit — file uploads need a different approach
- External clients can't call them reliably — the URL format changes between Next.js versions, breaking mobile apps or other services that point at Server Action endpoints directly
- Slower under high concurrency — API Routes outperform Server Actions in parallel-request benchmarks

</Section>

## API Routes: The Pattern for External Access

An API Route is a Route Handler at a URL. Export named functions matching HTTP methods. Anything that can make an HTTP request can call it.

```ts
// app/api/posts/route.ts
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { z } from "zod";

const createPostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(1),
});

export async function GET() {
  const posts = await db.posts.findMany({
    orderBy: { createdAt: "desc" },
  });
  return NextResponse.json(posts, {
    headers: {
      "Cache-Control": "public, max-age=60, stale-while-revalidate=300",
    },
  });
}

export async function POST(request: NextRequest) {
  const body = await request.json();
  const result = createPostSchema.safeParse(body);

if (!result.success) {
    return NextResponse.json(
      { error: result.error.flatten().fieldErrors },
      { status: 400 }
    );
  }

const post = await db.posts.create({ data: result.data });
  return NextResponse.json(post, { status: 201 });
}
```

**Where API Routes genuinely win:** Webhooks from Stripe, Clerk, Resend — they POST to a stable URL. Mobile apps that need a REST API. Cacheable GET endpoints with HTTP headers. Streaming responses. Any operation where you need full control over the HTTP response shape.

**Real webhook example:**

```ts
// app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const body = await request.text();
  const signature = request.headers.get("stripe-signature") as string;

let event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch {
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
  }

switch (event.type) {
    case "customer.subscription.deleted":
      await handleSubscriptionDeleted(event.data.object);
      break;
    case "invoice.payment_succeeded":
      await handlePaymentSucceeded(event.data.object);
      break;
  }

return NextResponse.json({ received: true });
}
```

</Section>

## Performance: The Numbers That Matter

<cite index="29-1">For mutations called from your app, Server Actions are typically faster because Next.js optimizes the request/response cycle. For read-heavy public APIs, Route Handlers with proper caching win.</cite>

The more important benchmark for production: <cite index="31-1">API Routes outperform Server Actions in high-concurrency scenarios.</cite> When many parallel requests hit the same endpoint simultaneously, API Routes handle the load more efficiently than Server Actions.

**The practical guidance:**

For a form submission from a single user, Server Actions are faster and simpler — no round-trip serialization overhead, no JSON parsing. For a public API endpoint receiving 50 simultaneous requests, API Routes handle the concurrency better.

The 1MB body limit on Server Actions is the most commonly hit production constraint. A file upload, a batch import, or a rich text editor with embedded images can easily exceed this. In those cases, use an API Route with a higher `bodySizeLimit` configuration, or upload directly to storage (S3, Supabase Storage) and pass only the URL to your action.

</Section>

## Security: What You Get vs What You Must Build

This is the section most guides don't cover thoroughly enough.

**Server Actions get three security features for free in Next.js 16:** ([source](https://www.verlua.com/blog/server-actions-vs-api-routes))

1. **Encrypted action IDs** — `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` hashes action references in the client bundle. This prevents replay attacks against renamed or removed actions — an attacker can't reverse-engineer a stable URL to call directly.

2. **Origin verification** — requests must come from the same origin as the page. Cross-origin calls to Server Actions are rejected at the framework level.

3. **CSRF protection** — the RPC handshake includes per-request tokens the framework validates before executing the function.

**API Routes get none of these by default.** You're responsible for verifying webhook signatures, implementing CSRF protection for state-changing endpoints, and handling origin validation.

That said — neither pattern replaces proper auth. A Server Action with CSRF protection is still exploitable if you don't verify the user owns the resource they're mutating. Always check authentication and authorization inside every protected action or route, regardless of which pattern you use:

```ts
// Both patterns need explicit auth
"use server";

import { getSession } from "@/lib/auth";

export async function deletePost(postId: string) {
  const session = await getSession();

if (!session?.user) throw new Error("Not authenticated");

const post = await db.posts.findUnique({ where: { id: postId } });

if (!post || post.authorId !== session.user.id) {
    throw new Error("Not authorized");
  }

await db.posts.delete({ where: { id: postId } });
}
```

</Section>

## Error Handling: Different Output Surfaces

Server Actions return values. API Routes return HTTP responses. The error handling pattern differs accordingly.

**Server Action — return error objects, use `useActionState`:**

```ts
"use server";

export async function createPost(formData: FormData) {
  try {
    // ...
    return { success: true };
  } catch (err) {
    console.error("[createPost]", err);
    // Never throw from a Server Action — return an error object
    return { success: false, error: "Something went wrong" };
  }
}
```

Don't throw from Server Actions unless you want the error to propagate to the nearest error boundary. Return structured error objects that your component can display.

**API Route — return HTTP status codes:**

```ts
export async function POST(request: NextRequest) {
  try {
    // ...
    return NextResponse.json(data, { status: 201 });
  } catch (err) {
    console.error("[POST /api/posts]", err);
    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
  }
}
```

Use correct status codes — 400 for bad input, 401 for unauthenticated, 403 for unauthorized, 404 for not found, 429 for rate limited, 500 for unexpected errors. External clients depend on these codes to handle failures programmatically.

</Section>

## Folder Structure

Keep both patterns in predictable, separate locations:

```
src/
  app/
    api/
      webhooks/
        stripe/
          route.ts
        clerk/
          route.ts
      v1/                    ← version public APIs from day one
        posts/
          route.ts
          [id]/
            route.ts
    actions/
      auth.ts
      billing.ts
      posts.ts
      profile.ts
```

Server Actions in `app/actions/`, organized by domain. API Routes in `app/api/`, organized by resource. Webhooks in their own subfolder. Version your public API with `v1/` from the start — adding versioning later is painful and usually breaking.

Never mix Server Action files into `app/api/`. It creates confusion about what's externally accessible and what isn't.

</Section>

## The Decision Framework

Ask these questions in order:

**Is the caller outside your Next.js app?**
Yes → API Route. Stripe webhooks, mobile apps, third-party integrations — they all need a stable URL.

**Is it a read operation that benefits from HTTP caching?**
Yes → API Route with a GET endpoint and `Cache-Control` headers.

**Is it a mutation triggered from your own UI?**
Yes → Server Action.

**Does the payload exceed 1MB?**
Yes → API Route, or upload to storage directly and pass the URL.

**Do you need to run under high concurrency from multiple simultaneous clients?**
Yes → API Route handles this better.

**Anything else?** Default to Server Action. You can extract to an API Route later if you need external access. Going the other direction adds boilerplate.

In practice, most SaaS apps end up with Server Actions handling 80–90% of server logic and API Routes covering webhook endpoints and whatever public API surface exists. That's the right default ratio.

</Section>

## Common Mistakes

**Using a Server Action for data fetching.** Server Actions are POST-only and can't be cached. Fetch data directly in Server Components — no hook, no action, just `await db.query()` inside an `async` component.

**Building an API Route for every internal mutation.** If only your own React code calls it, a Server Action is simpler — no fetch, no JSON parsing, automatic type safety, built-in CSRF protection.

**Not awaiting `cookies()`, `headers()`, or `params` in Next.js 16.** These are async in Next.js 16. The error message when you miss an await is a runtime crash that's hard to trace without knowing the cause.

**Assuming Server Actions are private.** The `"use server"` directive means "run on the server." It does not mean "only callable from authenticated users." Every Server Action that touches user data needs an explicit auth check inside the function.

**Pointing an external client at a Server Action URL.** The URL format Next.js generates for Server Actions is an implementation detail that changes between versions. If a mobile app or external service points at that URL and Next.js changes its format, the integration breaks silently. Use an API Route for any external integration.

</Section>

## Wrap Up

Server Actions and API Routes solve different problems. The confusion comes from the fact that both run on the server — but "runs on the server" is not what distinguishes them. The distinguishing factor is who calls them.

Start with Server Actions for anything your UI initiates. Add API Routes when you need external access, HTTP caching, high concurrency, or payloads over 1MB. Most apps need both — they're complementary, not competing.

If you're building a SaaS and want your project management, deployment tracking, and analytics in one workspace, check out [AdeptDev](https://adeptdev.io). Free for 7 days.

</Section>

## What is the difference between Server Actions and API Routes in Next.js?
Server Actions are async functions you call directly from React components — Next.js handles the HTTP request behind the scenes. They're POST-only, type-safe automatically, and get CSRF protection and encrypted action IDs from Next.js 16. API Routes are traditional HTTP endpoints at a stable URL that any HTTP client can call. Use Server Actions for internal mutations from your own UI. Use API Routes when external clients need to call your backend — webhooks, mobile apps, third-party integrations.

## When should I use a Server Action instead of an API Route?
Use a Server Action for any create, update, or delete operation that your own React UI triggers — form submissions, button clicks, profile updates, checkout steps. Server Actions remove the boilerplate of fetch calls and JSON handling, give you automatic type safety, and include built-in CSRF protection. The cases where you should not use a Server Action: GET requests (POST-only, not cacheable), payloads over 1MB, webhooks from external services, and any endpoint a mobile app or third-party service needs to call at a stable URL.

## Are Server Actions secure in Next.js 16?
Server Actions are more secure than API Routes by default. Next.js 16 ships three protections automatically: encrypted action IDs (hashed references that prevent replay attacks), same-origin verification (cross-origin calls are rejected at the framework level), and per-request CSRF tokens. API Routes get none of these by default — you're responsible for verifying webhook signatures and implementing CSRF protection. That said, neither pattern replaces explicit authentication. Every Server Action that touches user data needs an auth check inside the function — `"use server"` does not mean "only accessible by authenticated users."

## Can Server Actions replace API Routes entirely?
No. Server Actions can't replace API Routes for webhooks (Stripe, Clerk, Resend post to stable URLs), mobile app backends (the Server Action URL format changes between Next.js versions), cacheable GET endpoints, streaming responses, or high-concurrency public APIs. Server Actions are designed for mutations from your own React UI. Most production apps use both — Server Actions for 80-90% of server logic, API Routes for external-facing endpoints.

## What is the 1MB limit on Server Actions?
Server Actions have a default 1MB request body size limit. This catches most form submissions and JSON payloads, but fails for file uploads, batch imports, or rich text content with embedded images. If your use case involves large payloads, use an API Route instead — Route Handlers have a configurable body size limit. For file uploads specifically, the recommended pattern is to upload directly to object storage (S3, Supabase Storage, Cloudflare R2) from the client and pass only the resulting URL to a Server Action for database recording.

## What is `useActionState` and how does it work with Server Actions?
`useActionState` is a React 19 hook (it replaced the older `useFormState`) for handling Server Action responses and pending state in Client Components. You pass it the Server Action and an initial state value. It returns a tuple of `[state, action, isPending]` — the last value returned by the action, a wrapped action function to use as the form's action prop, and a boolean for showing loading UI. When the action completes, the state updates automatically and the component re-renders. It handles the full cycle of form pending state, error display, and success handling without manual fetch logic.

## How do params work in Next.js 16 API Routes?
In Next.js 16, route segment params in Route Handlers are returned as a Promise and must be awaited before use. Change your function signature to accept `{ params }: { params: Promise<{ id: string }> }` and add `const { id } = await params` before using any param values. The same async change applies to `cookies()`, `headers()`, and `draftMode()` throughout Next.js 16. Running `npx @next/codemod@canary upgrade latest` migrates these automatically in an existing codebase.

</FAQBlock></article></body></html>