Solución de problemas

Cuando un request falla, revisa primero el código de error y después el estado relacionado en Dashboard.

Diagnóstico rápido

Síntoma	Revisa primero
`invalid_api_key`	Header, key copiada, estado de key, expiración.
404 `model_not_found`	Spelling de model ID y alcance de modelos de la key.
`insufficient_quota`	Saldo de Billing y presupuesto de key.
400 `invalid_request`	JSON body, `messages`, `max_tokens`, `temperature`, `top_p`.
413 `request_too_large`	Tamaño de input. Reintentar el mismo payload no funciona.
429 `rate_limit_exceeded`	Request rate y `retry-after`.
429 `token_rate_limit_exceeded`	Volumen de tokens y `retry-after`.
504 `upstream_request_timeout`	timeout de cliente, velocidad de modelo, salud del proveedor.
`upstream_unavailable`	Disponibilidad de proveedor/canal u otro modelo.
`upstream_error` o `gateway_error`	Estado, proveedor o modelo alternativo.
Playground funciona pero local falla	Base URL local, variables de entorno, proxy, firewall.

`invalid_api_key`

El header debe ser:

Authorization: Bearer YOUR_NEXOROUTER_API_KEY

Causas comunes:

Falta Bearer.
No hay espacio después de Bearer.
Usas una key de OpenAI, Anthropic u otro proveedor.
Key disabled.
Key expirada.
Copia incompleta.
Variable de entorno no cargada en shell, dev server o deployment.

`model_not_found`

Usa Models o GET /v1/models como fuente de verdad.

curl https://api.nexorouter.com/v1/models \
  -H "Authorization: Bearer $NEXOROUTER_API_KEY"

Si el modelo aparece pero el request falla, revisa si la API key tiene alcance de modelos restrictivo.

`insufficient_quota`

Abre Billing y API Keys:

Revisa workspace balance.
Revisa presupuesto de key.
Revisa gasto reciente en Usage Logs.
Agrega saldo o crea una key con el presupuesto correcto.

Request too large

request_too_large es permanente para ese payload exacto. Reduce input, divide la tarea, resume contexto anterior o usa un modelo/ruta de mayor contexto cuando esté disponible en el catálogo público.

Rate limits

rate_limit_exceeded y token_rate_limit_exceeded incluyen headers de rate-limit y retry-after. Espera la ventana o reduce concurrencia.

No implementes reintentos en bucle cerrado. Los requests rate-limited se rechazan antes de llegar al proveedor, así que reintentar de inmediato normalmente repite el 429 hasta que la ventana se reinicia.

Timeouts

timeouts recomendados:

Tipo de modelo	timeout inicial
Chat estándar	`60` segundos
Modelo lento tipo reasoning	hasta `180` segundos

Si tu cliente cancela temprano y reintenta de inmediato, cada retry es un nuevo request.

Qué enviar a soporte

Envía:

email de cuenta;
hora del request;
request ID;
model ID;
código de error;
nombre de API key o últimos cuatro caracteres.

No envíes:

API key completa;
password;
datos de tarjeta;
private keys;
código fuente completo salvo que se pida por un canal privado de soporte.