> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thaliq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Problemas comunes y como resolverlos

## El widget no aparece

<AccordionGroup>
  <Accordion title="La API Key no es valida">
    Verifica que el atributo `data-api-key` tenga una key valida. Para widget publico recomendamos **Access Keys** (`tq_ak_...`, visibles desde el workspace). Tambien funcionan **API Keys** (`tq_live_...`), pero solo se ven una vez al crear. Crea/revisa keys en **Agente > Credentials**.
  </Accordion>

  <Accordion title="El script no se carga">
    Abre las **DevTools** del navegador (F12) y revisa la pestaña **Console** y **Network**. Verifica que la peticion a `cdn.thaliq.com/widget.js` se complete correctamente (status 200).
  </Accordion>

  <Accordion title="Conflicto de CSS">
    El widget usa clases con prefijo `thaliq-` para evitar conflictos. Si algun estilo de tu sitio interfiere, verifica que no haya reglas CSS globales agresivas (ej: `* { display: none !important; }`).
  </Accordion>

  <Accordion title="Script cargado despues del DOM">
    Si usas carga diferida (`defer`, `async`), el widget se auto-inicializa correctamente. Pero si lo cargas dinamicamente, asegurate de que el DOM este listo.
  </Accordion>
</AccordionGroup>

## El agente no responde

<AccordionGroup>
  <Accordion title="API Key revocada o expirada">
    Ve a **Agente > Credentials** y verifica que la key este activa. Si la revocaste, crea una nueva.
  </Accordion>

  <Accordion title="Rate limit alcanzado">
    Si ves el mensaje "Limite alcanzado", has excedido el limite de requests por minuto de tu plan. Espera el tiempo indicado o considera upgradear tu plan.

    Los limites estan documentados en [Planes y limites](/introduction/plans). En Enterprise no hay rate limit por defecto.
  </Accordion>

  <Accordion title="Sin tools configuradas">
    Si el agente necesita ejecutar acciones pero no tiene tools configuradas, puede que no responda como esperas. Ve a **Agente > Tools** y verifica la configuracion.
  </Accordion>
</AccordionGroup>

## Errores comunes en consola

### `[ThaliqWidget] API key is required`

No se proporciono `data-api-key` en el script tag o `apiKey` en el constructor.

```html theme={null}
<!-- Asegurate de incluir data-api-key -->
<script
  src="https://cdn.thaliq.com/widget.js"
  data-api-key="tq_live_xxx"
></script>
```

### Error HTTP 403

Tu API Key no tiene acceso a alguna funcionalidad. Esto puede significar:

* La feature requiere un plan superior
* La API Key fue creada para un tenant diferente

### Error HTTP 429

Has alcanzado el rate limit. El widget muestra automaticamente un mensaje con el tiempo de espera. Revisa los [limites de tu plan](/introduction/plans).

### Error de conexion / CORS

La API de Thaliq permite CORS desde cualquier origen. Si ves errores de CORS:

1. Verifica que la URL de la API sea correcta (`https://api.thaliq.com`)
2. Verifica que no haya un proxy o firewall corporativo bloqueando la conexion
3. Verifica que tu sitio use HTTPS (las peticiones HTTP a HTTPS pueden ser bloqueadas)

## El widget se ve mal en mobile

El widget automaticamente cambia a modo pantalla completa en pantallas menores a 480px. Si no se ve correctamente:

1. Asegurate de tener el meta tag viewport:
   ```html theme={null}
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   ```
2. Verifica que tu CSS no override estilos del widget

## Las acciones interactivas no aparecen

Si configuraste instrucciones con acciones (consent, confirm, etc.) pero no aparecen:

1. Verifica que la instruccion este **habilitada** en **Agente > Instructions**
2. Verifica que la instruccion este **asociada a la tool** correcta
3. Verifica que la tool tenga `requiresAuth: false` (para ser visible en el widget)
4. Recuerda que en planes **Free** y **Starter**, los tipos de accion estan limitados — ver [Planes](/introduction/plans)

<Note>
  **Las acciones se renderizan inline** dentro del mensaje del asistente, no como un mensaje aparte. Si esperabas un mensaje separado y no lo ves, mira **dentro** del mismo bloque de respuesta del agente — la accion (consent / confirm / select / form) aparece como una card embebida arriba o abajo del texto. Despues de aceptar/rechazar, la card cambia de estado (`pending` → `accepted`/`rejected`) y la respuesta del agente continua en el mismo bloque.
</Note>

## Aun necesitas ayuda?

Si el problema persiste, contactanos con:

* La URL de tu sitio web
* Captura de la consola del navegador (DevTools > Console)
* Tu plan actual y tenant ID

[Contactar soporte](https://thaliq.com/contact)