When to Use Edge vs Serverless Functions for API Calls

This guide is part of Vercel Edge Runtime vs Cloudflare Workers.

The edge vs serverless decision is not about which is “better”—it is about matching the runtime’s constraints to the API’s requirements. Getting this wrong shows up as 500 errors from missing Node.js modules, 413 errors from oversized payloads, or cold-start spikes that degrade perceived performance. Getting it right is largely a matter of following a decision tree based on your API’s actual characteristics, and the constraint that forces the split is the edge V8 isolate’s Web-API-only surface.

Symptom: Routing Misalignment

These symptoms indicate a mismatch between runtime and workload:

• Cold-start spikes during low traffic: P99 response times jumping from 50 ms to 800+ ms during lulls. This typically means a serverless function is deployed to an edge route with inadequate warm-up, or an edge function is doing heavy initialization work that belongs in a serverless container.
• 413 or immediate 500 errors: Uploading multipart form data or large JSON fails at the edge because the payload exceeds the 1 MB limit. A 500 with require('fs') not found means Node.js built-ins are being called in an edge runtime.
• Missing authentication headers: Set-Cookie being stripped or custom auth headers not propagating is a sign the edge runtime is dropping non-standard headers without the explicit forwarding configuration required.

Core Constraint Comparison

Decision Criteria

Use edge when ALL of the following are true:

1. The API uses only Web APIs (fetch, WebCrypto, ReadableStream).
2. Payloads are below 1 MB.
3. Sub-100 ms TTFB is required globally.
4. The operation is stateless (JWT validation, geo-routing, A/B testing, header injection).

Use serverless when ANY of the following are true:

1. The code uses Node.js built-ins (fs, child_process, native TCP connections).
2. Payloads routinely exceed 1 MB (file uploads, large JSON exports).
3. The operation requires a long-running connection or background processing > 30 s.
4. The logic uses database drivers that open direct TCP connections (Prisma without Accelerate, raw pg, mysql2).

Step 1: Audit Dependency Compatibility

Before routing to edge, verify your API’s imports:

// Edge-incompatible
import { createHash } from 'crypto';       // Node.js module
import fs from 'fs/promises';              // No filesystem at edge
import { Pool } from 'pg';                 // Raw TCP; not available

// Edge-compatible equivalents
const hashBuffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(data));
// Use platform KV / Blob storage instead of fs
// Use Prisma Accelerate, Hyperdrive, or an HTTP API instead of pg

Step 2: Route Traffic by Payload and Route Pattern

In Next.js, use middleware to direct traffic based on request characteristics:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(req: NextRequest) {
  const contentLength = Number(req.headers.get('content-length') ?? '0');

  // Large payloads must go to serverless; edge runtime will reject them
  if (req.nextUrl.pathname.startsWith('/api/upload') || contentLength > 900_000) {
    // Rewrite to a serverless-backed route
    const url = req.nextUrl.clone();
    url.pathname = `/api/serverless${url.pathname.replace('/api', '')}`;
    return NextResponse.rewrite(url);
  }

  // Cache GET responses at the edge CDN layer for public endpoints
  if (req.method === 'GET' && req.nextUrl.pathname.startsWith('/api/public/')) {
    const res = NextResponse.next();
    res.headers.set('Cache-Control', 's-maxage=60, stale-while-revalidate=300');
    return res;
  }

  return NextResponse.next();
}

export const config = { matcher: ['/api/:path*'] };

Step 3: Apply Runtime-Specific Caching and Timeout Rules

Edge routes:

• Use s-maxage for shared (CDN) caching; max-age for browser caching.
• Headers are effectively immutable after the response is created; clone to modify.
• Cache-Control: no-store on authenticated routes prevents cache poisoning.

Serverless routes:

• Implement connection pooling for database clients to amortize cold-start connection overhead.
• Guard against runaway executions with an explicit timeout:

const runWithTimeout = async <T>(
  promise: Promise<T>,
  limitMs: number,
  label: string
): Promise<T> => {
  const timeout = new Promise<never>((_, reject) =>
    setTimeout(() => reject(new Error(`Timeout: ${label} exceeded ${limitMs}ms`)), limitMs)
  );
  return Promise.race([promise, timeout]);
};

// For a 300 s platform limit, guard at 290 s to leave headroom for response serialization
const result = await runWithTimeout(heavyDatabaseQuery(), 290_000, 'heavyDatabaseQuery');

Production Validation Checklist

1. Simulate edge payload limits: Inject a 1.1 MB JSON payload to confirm your edge route returns 413 and your serverless fallback handles it correctly.
2. Verify Cache-Control in production: curl -I https://your-domain.com/api/public/endpoint | grep cache-control. Missing s-maxage means the CDN is not caching the response and you are invoking the function on every request.
3. Check cold-start duration: Use wrangler tail (Cloudflare) or vercel logs to confirm initDuration for serverless functions. If consistently > 500 ms, apply the dependency optimization patterns from Managing Cold Starts in Serverless Environments.
4. Monitor memory: Edge isolates cap at 128 MB. Watch OOM errors in platform dashboards; they indicate the workload belongs in a serverless function.

Pre-Ship Checklist

• Edge routes import zero node: Edge routes import zero `node:` built-ins; serverless fallbacks own anything that does.
• A 1.1 MB payload returns 413 A 1.1 MB payload returns `413` at the edge and is handled by the serverless route.
• Public GET responses carry s-maxage and stale-while-revalidate, confirmed via curl -I Public GET responses carry `s-maxage` and `stale-while-revalidate`, confirmed via `curl -I`.
• Serverless database clients use connection pooling and an explicit timeout guard.
• Edge isolate memory stays under 128 MB with no OOM errors in the dashboard.
• The middleware matcher targets only the routes that need tier-based rewriting.

Frequently Asked Questions

Conclusion

The decision is mechanical: if the API requires Node.js built-ins, payloads > 1 MB, or long-running TCP connections, it belongs in a serverless function. If it only needs Web APIs, handles small payloads, and benefits from sub-100 ms global latency, it belongs at the edge. Middleware that routes traffic between these two tiers based on request characteristics—payload size, path prefix, content type—is itself a valid edge-only workload with no Node.js dependencies and minimal compute requirements.

Related

• Vercel Edge Runtime vs Cloudflare Workers
• Vercel Edge vs Cloudflare Workers for authentication
• Streaming responses: Vercel Edge vs Cloudflare Workers
• Running A/B tests at the edge