Solución de Problemas — Documentación de TokSpan

Códigos de Error Comunes

Código	Mensaje	Causa	Solución
401	Clave API inválida	La clave falta, está mal formada o fue revocada	Verifica el encabezado `Authorization: Bearer sk-...`. Confirme que la clave esté activa en Panel → API Keys. Las claves comienzan con `sk-`.
404	Endpoint no encontrado	La URL de la solicitud no coincide con ningún endpoint de la API	Revisa la ruta de la solicitud contra la referencia de la API. Nota: los errores de modelo no encontrado se devuelven como `503` con código `model_not_found` — consulta Códigos de error.
429	Límite de tasa excedido / cuota insuficiente	Demasiadas solicitudes en la ventana actual, o el saldo de tu cuenta/clave API está agotado	Para limitación de tasa, implementa backoff exponencial con jitter. Si el mensaje de error menciona cuota o saldo (p. ej. `insufficient_user_quota`), recarga en Panel → Facturación en lugar de reintentar. Consulta Límites de Tasa.
500	Error interno del servidor	Problema del lado de TokSpan	Reintenta con backoff. Si persiste >5 min, consulte la página de estado.
502	Gateway incorrecto	El proveedor upstream está caído o agotando el tiempo de espera	Reintenta — el failover automático debería enrutar a un proveedor de respaldo que sirve el mismo modelo. Si persiste, contacta al soporte.
503	Servicio no disponible / modelo no encontrado	Sobrecarga temporal, o el modelo no está disponible para tu clave	Reintenta con backoff: no confíes en el encabezado `Retry-After`. Si el error incluye el código `model_not_found`, verifica el nombre del modelo en el catálogo de modelos; los nombres distinguen mayúsculas. Consulta la página de estado.

Problemas de Conexión

Errores "Connection refused" / "Name resolution failed"

Verifica la URL base: https://api.tokspan.com/v1 (nota: https://, no http://)
Verifica que tu firewall / proxy permita HTTPS saliente en el puerto 443
Prueba de DNS: nslookup api.tokspan.com debería devolver una IP

Error de certificado SSL

Asegúrate de que los certificados CA de tu sistema estén actualizados
Verifica que el reloj de tu sistema sea preciso (los certificados SSL dependen de la hora)
Usamos certificados de Let's Encrypt — son confiables en todos los sistemas operativos principales

Tiempo de espera agotado (Request Timeout)

El tiempo de espera predeterminado varía según el SDK. Establece explícitamente: 60s mínimo para chat, 120s para generaciones largas
Usa streaming (stream: true) — recibirá tokens sin esperar la respuesta completa
Si los tiempos de espera ocurren consistentemente con un modelo específico, el proveedor upstream puede estar lento — prueba un modelo más rápido o ligero

Lista de Verificación de Diagnóstico Rápido

Revisa estos puntos antes de abrir un ticket de soporte:

¿Es válida tu clave API? — Pruébala con este curl mínimo:

curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","messages":[{"role":"user","content":"Hi"}]}'

Si esto devuelve un 401, la clave es el problema. Si devuelve un 200 con contenido, tu clave y URL base son correctas.

¿Es correcto el nombre del modelo? — Consulta el catálogo de modelos. Error común: usar "gpt4" en lugar de "gpt-4o".
¿Tienes créditos? — Verifica en Panel → Facturación. El saldo debe ser > $0.
¿Está limitado por tasa o sin cuota? — Si recibes una respuesta 429, reduce la concurrencia y reintenta con backoff exponencial (usa el encabezado Retry-After si está presente). Si el error menciona cuota/saldo, verifica tus créditos en Panel → Facturación.
¿Está activo el servicio? — Consulta la Página de Estado de la API para ver incidentes en curso.

Problemas Específicos del SDK

Python (SDK de openai)

ModuleNotFoundError: openai → pip install openai
openai.APIError / APIConnectionError → Verifica la conectividad de red. Prueba curl directamente para aislar problemas del SDK vs. red.
Proxies: Configura http_client=httpx.Client(proxy="http://proxy:8080") si estás detrás de un proxy corporativo

Node.js (SDK de openai)

Cannot find module 'openai' → npm install openai
ERR_MODULE_NOT_FOUND → Usa import con ESM o require('openai') con CJS
fetch is not defined (Node < 18) → Actualiza a Node 18+ o haz polyfill de globalThis.fetch

¿Sigue Atascado?

Incluye lo siguiente al contactar al soporte — acelera drásticamente la resolución:

El correo electrónico de tu cuenta
El ID de solicitud de la respuesta de error (campo id)
El cuerpo completo de la respuesta de error y el código de estado HTTP
El modelo que estás llamando y un fragmento de código mínimo que reproduzca el problema
La versión de tu SDK (pip show openai / npm list openai)

Envíanos un correo a support@tokspan.com — respondemos en un plazo de 24 horas.