Solución de errores 401, 403, 429 y 5xx

Doce fallos concretos que vemos semana tras semana. Síntoma → causa → arreglo en una línea.

Preguntas principales

¿Necesito iniciar sesión en Claude Code? ¿Qué hacer con 401 y “Auth conflict”?

No. La clave de OneProvider funciona sin una cuenta de Claude. Para Claude Code define ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN (la clave se envía como Authorization: Bearer). Esta variable tiene prioridad sobre una sesión guardada y sobre las demás variables, y no pide aprobación. Nuestro gateway también acepta ANTHROPIC_API_KEY (encabezado x-api-key), pero en modo interactivo Claude Code te pide una vez que apruebes esa clave y ignora en silencio una que rechazaste (vuelve a activarla en /config → Use custom API key).

Si ves la pantalla de inicio de sesión, 401 Invalid API key o Auth conflict, ve paso a paso:

1. Ejecuta /status: debe mostrar la Anthropic base URL de OneProvider y una línea Auth token o API key con el nombre de tu variable. Una línea Login method con una cuenta de claude.ai significa que la variable no llegó a la sesión.
2. Auth conflict (hay a la vez una sesión de claude.ai y una clave): ejecuta /logout; tus variables se conservan.
3. 401 Invalid API key: un ANTHROPIC_AUTH_TOKEN ajeno (un token de otro servicio) anula tu clave, o el valor trae una comilla o un espacio de más. Ponle la clave completa de OneProvider, sin comillas.
4. La pantalla de inicio de sesión sigue aunque las variables estén en el .claude/settings.json de un proyecto: ese bloque se lee después de la configuración inicial, así que pon las variables en tu shell o en ~/.claude/settings.json.

# macOS / Linux: what is actually set
env | grep -E 'ANTHROPIC_(BASE_URL|AUTH_TOKEN|API_KEY)' | sed -E 's/(sk-.{4}).*/\1.../'
grep -nE 'ANTHROPIC_(AUTH_TOKEN|API_KEY)' ~/.zshrc ~/.bashrc 2>/dev/null

¿Necesito iniciar sesión en ChatGPT para usar Codex CLI?

No. Codex funciona solo con la clave cuando el proveedor oneprovider de ~/.codex/config.toml está activo (env_key = "ONEPROVIDER_API_KEY"). Si aparece la petición de iniciar sesión en ChatGPT o “You've hit your usage limit”, el proveedor no está activo y la solicitud fue a ChatGPT.

Revisa en este orden: las líneas model_provider y model están justo al principio del archivo, encima de cualquier [table]; Codex está completamente reiniciado y la tarea es nueva; la clave está exportada en la misma terminal:

codex logout
export ONEPROVIDER_API_KEY="sk-..."
# quick test without editing the file:
codex -c model_provider=oneprovider

Guía completa en la página de Codex (OpenAI) .

¿Necesito una VPN? ¿Hay restricciones regionales?

No hace falta VPN: OneProvider no tiene restricciones regionales. El endpoint api.oneprovider.dev es accesible desde todo el mundo y no bloquea el tráfico por geolocalización.

Peor aún, las VPN y los proxies VLESS suelen romper la conexión con la API de dos maneras:

• El streaming SSE se almacena en búfer dentro del proxy y el stream se corta a mitad de un token.
• La negociación HTTP/2 + ALPN falla en los saltos del relay: el cliente ve connection reset.

Si ves streams cortados, connection reset o timeouts aleatorios, desactiva la VPN o el proxy VLESS y reintenta. De nuestro lado no almacenamos los streams en búfer.

Error de análisis JSON en la configuración (o un 429)

La causa más común son las comillas “inteligentes” (“ ”) en tu configuración JSON. Aparecen al copiar desde un mensajero, Notion, Google Docs o un navegador que cambia las comillas ASCII por tipográficas. Los analizadores JSON solo aceptan la comilla recta ASCII ".

A veces una configuración rota no se muestra como “JSON parse error” sino como un 429: el cliente interpreta la falta de respuesta como un límite de frecuencia. La solución es la misma:

• Reemplaza a mano cada “ ” por ".
• Copia las configuraciones directamente de esta documentación: aquí las comillas ya son correctas.
• Valida con cat -v config.json o jq . config.json: ambos señalan el byte incorrecto.

# Quick check: jq fails on the first smart quote
jq . ~/.claude/settings.json
# Auto-replace smart quotes with straight quotes
sed -i.bak $'s/[\u201c\u201d]/"/g' ~/.claude/settings.json

Matriz de síntomas

Comandos de diagnóstico en una línea

Si la matriz de síntomas no cubrió tu caso, reúne estas tres pruebas:

# 1. Confirm reach + auth
curl -sS -o /dev/null -w "HTTP %{http_code} total %{time_total}s\n" \
https://api.oneprovider.dev/v1/models -H "x-api-key: $ANTHROPIC_API_KEY"
# 2. Reproduce the failing call with -v (verbose headers)
curl -sv https://api.oneprovider.dev/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5-5","max_tokens":32,"messages":[{"role":"user","content":"hi"}]}'
# 3. Check your current balance (also shown in the cabinet: the @oneprovider_robot bot or app.oneprovider.dev)
curl -s https://api.oneprovider.dev/v1/dashboard/balance \
-H "Authorization: Bearer $ANTHROPIC_API_KEY"

Cuándo escalar

Envía las tres salidas de arriba + los primeros 8 caracteres de tu clave + una marca de tiempo UTC a @Oneproviderhelpbot . Con eso encontramos tu solicitud en nuestros registros en minutos. Consulta Obtener soporte para saber qué no necesitamos (y nunca pedimos).