Vercel error 500 (y error 403): causas y cómo arreglarlo

El error 500 en Vercel significa que algo falló del lado del servidor al responder. En la gran mayoría de los casos es una función de servidor (en /api, rutas de Next.js, middleware) que truena por una excepción no controlada o por una variable de entorno que no existe en Vercel. La causa exacta siempre está en los Logs del proyecto. También te explicamos el error 403, que suele ser la protección de deploys de Vercel.

Paso 1: identifica el tipo de 500

Vercel muestra un código junto al error. Los más comunes:

Código	Qué significa
FUNCTION_INVOCATION_FAILED	La función tronó (excepción no controlada o proceso caído)
FUNCTION_INVOCATION_TIMEOUT	La función tardó más del límite permitido
MIDDLEWARE_INVOCATION_FAILED	Falló el middleware (código que corre antes de cada petición)
Sin código de Vercel, con tu propio mensaje	Tu código devolvió 500 a propósito

La lista completa está en la documentación de errores de Vercel.

Paso 2: lee los logs

Según la guía de FUNCTION_INVOCATION_FAILED:

1. En el dashboard de Vercel, abre tu proyecto.
2. Entra a la pestaña Logs.
3. Reproduce el error y búscalo por hora o por código 500.
4. Abre la entrada: verás el mensaje y la línea del error.

Lo que buscas se ve así:

TypeError: Cannot read properties of undefined (reading 'split')
    at handler (/var/task/api/checkout.js:12:34)

Causas más comunes y cómo arreglarlas

1. Variables de entorno faltantes

Tu función usa process.env.STRIPE_SECRET_KEY o process.env.SUPABASE_SERVICE_ROLE_KEY y en Vercel no existe. En local funciona porque está en tu .env.

Solución: Settings → Environment Variables, agrega la variable con el mismo nombre, en el entorno correcto (Production y/o Preview) y vuelve a hacer deploy: los cambios de variables no se aplican a deploys anteriores. Ver qué es el archivo .env.

2. Excepciones no controladas

Una promesa sin await, un dato que llega vacío o una API externa que falla. Vercel recomienda envolver la lógica en try/catch para registrar el error en vez de tumbar el proceso:

export async function GET(request: Request) {
  try {
    const data = await obtenerDatos();
    return Response.json(data);
  } catch (err) {
    console.error("Falló /api/datos:", err);
    return Response.json({ error: "Error interno" }, { status: 500 });
  }
}

3. API externa caída o llave inválida

Si tu función llama a Stripe, Supabase, OpenAI o Mercado Pago y ellos responden error, tu función puede convertirlo en 500. El log dirá algo como Invalid API Key o 401. Revisa la llave y la página de estado del servicio.

4. Tiempo agotado

FUNCTION_INVOCATION_TIMEOUT aparece cuando la función tarda más del máximo de tu plan. Los límites cambian por plan; consúltalos en la documentación de límites de funciones. Soluciones: optimiza la consulta, mueve trabajos pesados a un proceso en segundo plano o revisa si una llamada externa se está quedando colgada.

5. Base de datos

Muchas conexiones abiertas, una tabla que no existe en producción o reglas de permisos. Revisa también los logs de tu base de datos (en Supabase: Logs).

Casos frecuentes en apps hechas con IA

Cuando la app viene de v0, Bolt, Cursor u otra herramienta de IA, estos son los patrones que más se repiten detrás de un 500:

• Funciona en local y truena en Vercel solo en una página. Esa página corre en el servidor (un Server Component o una ruta de API de Next.js) y lee una variable que en tu computadora sí existe. Busca en el código process.env. y compara la lista con lo que tienes en Vercel.
• Librería que no funciona en el runtime Edge. Si la ruta o el middleware usa export const runtime = "edge", no tiene todas las APIs de Node.js (como fs). La IA a veces lo agrega sin necesidad. El log suele mencionar un módulo que no se encontró.
• Prisma sin generar. Con Prisma, si el cliente no se genera durante el build, el error aparece al consultar la base. Agrega prisma generate al script de build o como postinstall, como indica la documentación de Prisma para Vercel.
• El middleware protege todo, incluso archivos estáticos. Un error en el middleware tumba cada petición. Revisa el matcher para que solo cubra las rutas que deben protegerse.
• Se llama a la propia API con localhost. En el servidor de Vercel, http://localhost:3000 no existe. Usa rutas relativas o la URL real del sitio.

Después de arreglarlo

Haz un deploy nuevo, repite la acción que fallaba y vuelve a revisar los Logs. Si el error desaparece pero aparece otro, es normal: el primero tapaba al siguiente.

Error 403 en Vercel

El 403 no es una falla: es acceso denegado. Lo más común:

Deployment Protection

Vercel puede exigir que el visitante inicie sesión para ver ciertos deploys. Según la documentación de Deployment Protection, con Standard Protection se protegen todos los deploys excepto los dominios de producción; con All Deployments se protege todo.

Por eso pasa que tu dominio funciona, pero la URL de vista previa (tu-proyecto-abc123.vercel.app) da 403 o pide login a tus clientes.

Para revisarlo: proyecto → Settings → Deployment Protection. Si quieres compartir una vista previa con alguien sin cuenta de Vercel, la documentación ofrece métodos para crear excepciones o enlaces compartibles. No desactives la protección de todo el proyecto si no lo necesitas.

Otros 403

• Tu propio código o middleware bloquea la ruta (por ejemplo, exige sesión).
• Reglas del firewall de Vercel o de Cloudflare (si tu dominio pasa por Cloudflare).
• Un archivo o ruta a la que no tienes permiso.

Qué revisar antes de pedirle a la IA que lo arregle

1. Copia el log completo del error (no solo “500”).
2. Anota qué ruta falla y qué acción del usuario lo provoca.
3. Revisa si pasa en Preview y en Production o solo en uno (suele indicar variables distintas).
4. Pégalo todo junto. Ver corregir código con IA.

Si el build ni siquiera termina, el problema es otro: npm run build exited with 1. Si ves 404 en lugar de 500, ve a error 404 en Vercel.

Si tu app en Vercel falla con usuarios reales, sobre todo en pagos o inicio de sesión, en Black Engine revisamos los logs y la configuración contigo por WhatsApp.