Errores comunes de la API en Cursor: 401, 404, 429 y fallos de conexión (2026)

Al introducir una API Key y una Base URL personalizadas en Cursor, los errores suelen concentrarse en cuatro capas: credenciales, ruta, límites de velocidad y red. Muchas personas, al ver un aviso en rojo, cambian de modelo, y así convierten un problema de configuración en medio día perdido. El orden correcto es revisar primero el código de estado, reproducir con una solicitud mínima y solo después cambiar el modelo o el prompt.

Este artículo desglosa los errores 401, 404, 429, los fallos de conexión, las interrupciones de streaming y el contexto excedido, y ofrece comandos de diagnóstico, campos de registro y una lista de soporte ejecutable.

Aviso: Cursor es una marca registrada de Anysphere, Inc. Las versiones de Cursor se actualizan con rapidez y los menús de configuración y los mensajes de error pueden cambiar; este artículo toma como ejemplo las versiones habituales a octubre de 2026 y se rige por la versión instalada y la documentación oficial.

1. Orden de diagnóstico: primero las capas, después la configuración

Código o síntoma	Significado habitual	Qué revisar primero	¿Reintentar?
401	Clave ausente, incorrecta, caducada o sin permiso	Clave, campo de autenticación, estado de la cuenta	No reintentar
403	La clave no tiene permiso de modelo o la política del equipo la bloquea	Permisos de modelo, configuración del equipo	No reintentar
404	Ruta incorrecta o modelo inexistente	Base URL, ID de modelo	No reintentar
429	Frecuencia, concurrencia o cuota de tokens excedidas	Consumo, claves compartidas, política de reintentos	Reintentar con retroceso
400/413	Formato de solicitud incorrecto o contexto demasiado largo	Contexto, parámetros, max_tokens	Corregir y reintentar
5xx	Error del servidor o gateway sobrecargado	Estado del servicio, ID de solicitud	Reintentar con retroceso
Fallo de conexión	DNS, TLS, proxy, firewall	Ruta de red	Reintentar tras corregir

Primero fija una variable: la misma clave, la misma Base URL y el mismo ID de modelo; cambia solo un elemento antes de volver a probar. Si cambias tres cosas a la vez y funciona, no sabrás cuál lo resolvió.

2. 401: revisa primero la clave y después el campo de autenticación

Un 401 indica que la identidad no superó la verificación y no tiene relación con la capacidad del modelo ni con la longitud del contexto. Revisa en este orden:

Comprueba que la clave se copió completa y que no tiene espacios, saltos de línea ni comillas delante o detrás. Copiar desde una ventana de chat es la forma más fácil de arrastrar caracteres invisibles.
Comprueba que la clave está en el campo del proveedor correcto. En Cursor, OpenAI, Anthropic, Google y Azure son campos separados; si te equivocas de campo, obtendrás un 401 directamente.
Comprueba si la clave fue eliminada, deshabilitada o caducada. Revisa el estado en la consola del gateway, no solo en un archivo local.
Comprueba si la cuenta tiene saldo o cuota disponible. Algunos gateways devuelven 401 o 403 cuando el saldo es insuficiente; revisa el cuerpo del error.
Comprueba si el equipo prohíbe las claves de terceros personales. En Cursor, los planes Teams y Enterprise pueden bloquear BYOK desde la administración; en ese caso, la configuración local fallará aunque sea correcta.
Comprueba si la Base URL apunta al entorno al que pertenece la clave. Una clave de entorno de pruebas configurada contra la dirección de producción también suele dar 401.
Comprueba si las variables de entorno se cargaron realmente. Imprime solo los cuatro primeros y los cuatro últimos caracteres de la clave; no escribas la clave completa en los registros.

# Prueba mínima de autenticación: solo comprueba dirección, clave y protocolo
export API_KEY="sk-tu-clave"

curl -sS -o /tmp/cursor_resp.json -w "%{http_code}\n" \
  "https://api.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $API_KEY"

cat /tmp/cursor_resp.json

Si devuelve 200, la clave y la dirección funcionan en lo básico; si devuelve 401, prueba la misma clave en la entrada de pruebas de la consola del gateway para distinguir si el problema está en la clave o en el campo o la red de Cursor.

3. 404: la Base URL y el ID de modelo se reparten la culpa

Un 404 no significa necesariamente que el modelo se haya retirado; la causa más común es una ruta mal escrita:

Falta /v1 en la Base URL y la solicitud llega a la ruta web del sitio, que devuelve HTML o 404.
La Base URL incluye /v1/chat/completions y el cliente vuelve a añadirlo, de modo que queda /v1/chat/completions/chat/completions.
Se introduce /v1/messages de Anthropic en un campo compatible con OpenAI, o al revés.
El dominio está mal escrito o se usa la dirección de la consola como dirección de API.

El ID de modelo también puede provocar 404 o model_not_found:

Mayúsculas, guiones y número de versión deben coincidir exactamente con la página de precios o la lista de modelos.
Puede que el modelo no esté disponible para la cuenta o el plan actual.
Un mismo modelo puede tener ID distintos según el protocolo.
El botón Verify de Cursor normalmente solo comprueba la conectividad de la clave y la dirección; no confirma que el ID de modelo sea correcto. Debes verificarlo con una solicitud real.

Para diagnosticar, visita primero /v1/models (si el gateway lo ofrece) y copia el ID de modelo de la lista devuelta; no lo escribas a mano.

4. 429: el límite de velocidad no es falta de saldo

Un 429 indica que la solicitud superó el límite de frecuencia, concurrencia o cuota de tokens. Situaciones habituales:

Se excede el número de solicitudes por minuto o de tokens por minuto.
Varias personas comparten una clave y compiten por la misma cuota.
Agent lee archivos y ejecuta comandos de forma continua y envía muchas solicitudes en poco tiempo.
Los reintentos no usan retroceso y cada fallo genera más solicitudes, hasta formar una tormenta de reintentos.
Las solicitudes con contexto largo consumen más cuota y dejan menos margen para la concurrencia.

Al gestionarlo, revisa primero las cabeceras de respuesta y el cuerpo del error; no dupliques los reintentos a ciegas. Si hay Retry-After, espera ese tiempo; si no, aplica retroceso exponencial con fluctuación aleatoria. No reintentes los errores 401 y 404: reintentar solo amplifica el problema.

import random
import time

def retry_delay(attempt, base=1.0, cap=30.0):
    delay = min(cap, base * (2 ** attempt))
    return delay + random.uniform(0, delay * 0.3)

for attempt in range(4):
    response = send_request()  # sustituye por tu función de solicitud
    if response.status_code not in (429, 500, 502, 503, 504):
        break
    time.sleep(retry_delay(attempt))

Si los 429 se concentran en franjas horarias fijas, implanta primero una cola y un envío suavizado; si una sola clave atiende varios servicios, sepárala por proyecto; si el problema es un bucle de Agent, fija un número máximo de rondas y un límite de gasto.

5. Fallo de conexión: SSL, proxy y DNS

Los fallos de conexión normalmente no devuelven un código HTTP; se manifiestan como tiempo de espera agotado, ECONNRESET, errores de certificado o "no se puede conectar al servidor". Orden de diagnóstico:

Usa curl -Iv para ver en qué paso se detiene la resolución DNS, la conexión TCP y el handshake TLS.
Comprueba si el certificado caducó, si es autofirmado o si la red corporativa lo sustituye. Cuando un proxy empresarial inspecciona TLS, hay que instalar el certificado raíz de la empresa en la cadena de confianza del sistema.
Comprueba si las variables de proxy solo afectan a la terminal y Cursor no las usa. Revisa la configuración de red y proxy de Cursor y, si hace falta, compara conexión directa y proxy.
Comprueba si la VPN, el firewall o el software de seguridad bloquean conexiones persistentes o respuestas en streaming.
Comprueba que la hora del sistema sea correcta. Una desviación grande hace fallar la validación del certificado.
Comprueba si HTTP/2 o la reutilización de conexiones se ven interferidos por un dispositivo intermedio. Prueba primero con una solicitud corta y sin streaming.

No uses "el ping funciona" para decidir si la API está disponible. El ping solo demuestra que el host responde, no que TLS, el certificado y la ruta sean correctos.

6. Interrupciones de streaming y contexto excedido

Una salida en streaming se interrumpe por tres causas habituales: el proxy almacena en búfer el SSE, la conexión supera el tiempo de inactividad o el modelo alcanza un límite durante la generación. Se manifiesta como una respuesta que se detiene a medias, stream ended unexpectedly o un indicador de Cursor que gira sin parar.

Método de diagnóstico:

Envía la misma solicitud con "stream": false. Si la versión sin streaming funciona, el problema está en la cadena de streaming o en el proxy.
Prueba con curl -N en conexión directa para descartar factores del cliente Cursor.
Reduce max_tokens y la longitud del contexto para ver si la interrupción continúa.
Comprueba si el proxy tiene activado el búfer de respuesta y, si es necesario, usa conexión directa para el dominio de la API.
Para tareas largas de Agent, define tiempos de espera y un número máximo de rondas para evitar conexiones colgadas.

El contexto excedido suele devolver 400 o 413, y el cuerpo del error incluye textos como context_length_exceeded o maximum context length. Cursor envía juntos los archivos abiertos, los fragmentos recuperados y el historial de la conversación, así que el contexto real suele ser más largo de lo que imaginas. Soluciones: excluye artefactos de compilación y registros con un archivo de ignorados, cierra pestañas que no uses, resume los documentos largos y abre una conversación nueva cuando el historial sea muy extenso.

7. Cómo conservar registros útiles para el soporte

Registra al menos estos campos: hora, código de estado, código de error, ID de modelo, nombre de host de la Base URL, ID de solicitud, duración y número de reintentos. El ID de solicitud suele ir en las cabeceras de respuesta, con nombres como request-id, x-request-id o x-oneapi-request-id, según lo que devuelva realmente el gateway.

Un registro útil tiene este aspecto:

2026-10-19T10:12:33+08:00 status=429 code=rate_limit_exceeded model=tu-model-id host=api.zhongshangqihang.com request_id=... latency_ms=1840 retry=2

No registres la clave completa, el prompt completo ni el código del usuario. De la clave, conserva solo los cuatro primeros y los cuatro últimos caracteres, y anonimiza el contenido sensible. Cuando pidas soporte, un registro con un ID de solicitud vale más que diez capturas de pantalla.

8. Lista de soporte

Anota el texto original del error, el código de estado, la hora y el ID de solicitud.
Reproduce la misma solicitud con curl para confirmar si el problema solo aparece dentro de Cursor.
Revisa la Base URL: la compatibilidad con OpenAI suele llegar hasta /v1; Claude Code usa la dirección raíz.
Revisa el ID de modelo: cópialo de la lista de modelos y confirma mayúsculas y número de versión.
Prueba con una clave nueva para descartar una clave inválida, falta de cuota o una política de equipo.
Empieza con una solicitud sin streaming y contexto corto; después vuelve a activar streaming y contexto largo de forma gradual.
Cambia de red o de proxy para descartar DNS, TLS y proxies corporativos.
Si todo lo anterior pasa, envía los registros y los pasos de reproducción al soporte del gateway o de Cursor.

9. Preguntas frecuentes

La clave funciona en otro lugar, pero en Cursor da 401. ¿Por qué?

Revisa primero si está en el campo del proveedor correcto y después si la Base URL corresponde al entorno de la clave. En planes de equipo, confirma también que el administrador no haya prohibido las claves de terceros personales.

¿Un 404 significa siempre que el modelo fue retirado?

No. En la mayoría de los casos falta o sobra /v1 en la Base URL, o el ID de modelo está mal escrito. Visita primero la lista de modelos y copia el ID para probar.

¿Un 429 es falta de saldo?

No necesariamente. Un 429 indica que se superó un límite de velocidad o de cuota; la falta de saldo puede devolver 401, 402 o 403 según el gateway. Guíate por el cuerpo del error y la página de facturación.

¿Se pueden usar modelos de Claude directamente en Cursor?

Puedes usar una clave de Anthropic o llamar a través del protocolo OpenAI de un gateway compatible. En las versiones habituales, el campo de Anthropic no permite sobrescribir la Base URL; al conectar un gateway suele elegirse OpenAI Compatible y se introduce el ID de modelo exacto.

¿Por qué solo fallan las solicitudes en streaming?

Sospecha primero del búfer del proxy, del tiempo de inactividad y de la reutilización de conexiones. Compara con una solicitud sin streaming y prueba curl -N en conexión directa; normalmente así se localiza el tramo problemático de la cadena.

Siguiente paso

Primero crea una clave de prueba en ZSQH AI Gateway y ejecuta con los comandos curl de este artículo las pruebas de autenticación, modelo y streaming; después introduce la configuración en Cursor. La disponibilidad de los modelos y los precios se rigen por Precios de modelos. Al diagnosticar, fija primero las variables y cambia los elementos uno por uno.

Lecturas relacionadas:

Aviso: Cursor es una marca registrada de Anysphere, Inc.; OpenAI, Anthropic, Claude y Google son marcas de sus respectivos titulares. Este artículo solo discute tareas de diagnóstico técnico y no implica afiliación ni relación de cooperación con las empresas mencionadas. Los mensajes de error, los menús y el comportamiento de las interfaces pueden cambiar según la versión; consulta la documentación oficial.