Solución de Problemas

Códigos de Error Comunes

Problemas de Conexión

Errores "Connection refused" / "Name resolution failed"

• Verifique la URL base: https://api.tokspan.com/v1 (nota: https://, no http://)
• Verifique que su firewall / proxy permita HTTPS saliente en el puerto 443
• Prueba de DNS: nslookup api.tokspan.com debería devolver una IP
• Si se encuentra en una región con acceso a internet restringido, puede necesitar auto-hospedar

Error de certificado SSL

• Asegúrese de que los certificados CA de su sistema estén actualizados
• Verifique que el reloj de su 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. Establezca explícitamente: 60s mínimo para chat, 120s para generaciones largas
• Use 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 — pruebe un modelo diferente o agregue el sufijo -fast

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

Revise estos puntos antes de abrir un ticket de soporte:

1. ¿Es válida su clave API? — Pruébela 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":"gpt-4o","messages":[{"role":"user","content":"Hi"}]}'

   Si esto devuelve un 401, la clave es el problema. Si devuelve un 200 con contenido, su clave y URL base son correctas.
2. ¿Es correcto el nombre del modelo? — Consulte el catálogo de modelos. Error común: usar "gpt4" en lugar de "gpt-4o".
3. ¿Tiene créditos? — Verifique en Panel → Facturación. El saldo debe ser > $0.
4. ¿Está siendo limitado por tasa? — Verifique los encabezados de respuesta para x-ratelimit-remaining-requests. Si es 0, espere a que se reinicie la ventana.
5. ¿Está activo el servicio? — Consulte 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 → Verifique la conectividad de red. Pruebe curl directamente para aislar problemas del SDK vs. red.
• Proxies: Configure http_client=httpx.Client(proxy="http://proxy:8080") si está detrás de un proxy corporativo

Node.js (SDK de openai)

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

¿Sigue Atascado?

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

• El correo electrónico de su 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á llamando y un fragmento de código mínimo que reproduzca el problema
• La versión de su SDK (pip show openai / npm list openai)

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