Ayuda

Guía rápida cuando algo falla en el chat, el panel o un overlay. Los mensajes citados son los que devuelve la API en la práctica.

Antes de reportar

Comprueba Tu API Key, que la URL del comando sea correcta y que no hayas superado los límites. Si regeneraste la clave, actualiza todos tus bots.

---

Códigos HTTP habituales

Código	Significado	Qué hacer
200	Petición OK	En comandos de chat el cuerpo es texto plano. Algunos errores de auth también llegan como 200 con mensaje legible (no confundas con éxito).
400	Parámetros inválidos	Revisa channel, user, limit, etc. En JSON verás VALIDATION_ERROR con el campo concreto.
401	Sin auth o clave inválida	Añade apiKey o X-Api-Key. Si regeneraste la clave, actualiza el bot.
403	Cuenta suspendida o sin permiso	Contacta soporte si no conoces el motivo. En panel: CSRF rechazado → recarga la página.
429	Rate limit	Espera ~1 minuto (bots) o revisa si es límite pesado (clips/chatters: 5–40/min según rol).
500	Error interno	Reintenta en unos minutos. Si persiste, Discord con hora y endpoint.

---

Comandos de chat (bots)

Los bots (Nightbot, StreamElements, Fossabot, Wizebot) llaman la API con una URL. La respuesta suele ser texto plano que el bot imprime en el chat.

AutenticaciónTodos los endpoints requieren el parámetro apiKey en la query. Obtén la tuya desde el panel.›

Comportamiento en bots

Errores de API Key y de negocio devuelven **HTTP 200** con el mensaje en el cuerpo (así Nightbot y StreamElements lo muestran en el chat). El rate limit (**429**) devuelve **cuerpo vacío**.

Errores de autenticación y límites

En comandos de chat, muchos fallos de API Key llegan como 200 con un mensaje en el cuerpo — no como 401. El rate limit sí devuelve 429 (cuerpo vacío).

Mensajes en el chat

Falta API KeyKey inválidaKey expirada429 (vacío)

Error: Falta API Key. Debes incluir ?apiKey=TU_KEY en la URL.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Cache-Control: public, s-maxage=10, stale-while-revalidate
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

Error: Falta API Key. Debes incluir ?apiKey=TU_KEY en la URL.

⛔ Tu API Key no es válida. Regenerala en el dashboard o contacta con Ponss.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Cache-Control: public, s-maxage=10, stale-while-revalidate
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

⛔ Tu API Key no es válida. Regenerala en el dashboard o contacta con Ponss.

Error de autenticación. Clave API inválida o expirada. Regenerala o pide ayuda a Ponss 🦆

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Cache-Control: public, s-maxage=10, stale-while-revalidate
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

Error de autenticación. Clave API inválida o expirada. Regenerala o pide ayuda a Ponss 🦆

(sin contenido)

HTTP/1.1 429 Too Many Requests
Content-Type: text/plain; charset=utf-8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

Qué hacer

Escenario	Causa habitual	Solución
Falta API Key	La URL del comando no incluye apiKey.	Copia la clave en Configuración → Seguridad. Añade &apiKey=TU_CLAVE o usa el generador del panel (Followage, Clips…).
Key inválida o expirada	Clave mal copiada, regenerada o cuenta eliminada.	Abre Configuración → Seguridad, copia la clave actual o regenera y actualiza todos los bots. Ver Tu API Key.
Rate limit	Superaste el límite de tu rol (30–120 req/min).	El bot suele no decir nada (429 con cuerpo vacío). Espera ~1 minuto antes de reintentar. Ver Límites.

Tras regenerar la API Key

La clave anterior deja de funcionar al instante. Si el chat sigue mostrando «Key inválida», el bot aún tiene la URL antigua pegada.

1. Configuración → Seguridad → copia o regenera la API Key.
2. En cada bot, edita el comando y sustituye la clave en la URL (o vuelve a copiar desde el generador del panel).
3. Prueba con Probar API en el panel antes de usar el comando en vivo.

Parámetros y sintaxis

Síntoma en chat	Causa	Qué hacer
Falta el parámetro channel	Sin channel en la URL	Añade channel=TU_CANAL (login sin @).
Faltan parámetros: channel y user	Followage u otro comando sin user	Nightbot: $(touser) · StreamElements: ${user} · Wizebot: $(user_name).
«no sigue a…» (Followage)	El usuario no sigue el canal o el login está mal	Comprueba el nombre en Twitch; la API responde 200 con ese texto.
El bot no dice nada	URL mal pegada o sin urlfetch / customapi	Revisa la sintaxis en la doc del comando, p. ej. Followage.

Límite de Twitch (no es LosPerris)

Clips y datos en vivo

Si falla al crear o listar clips, Twitch puede haber limitado la petición. Espera 1–5 minutos y reintenta. No spamees !clip ni el JSON de Listar clips.

---

Panel y sesión

El dashboard usa cookie de sesión HttpOnly (lp_sess), no la API Key de los bots. Límite: 500 req/min (ver Límites).

Solo dashboard

AutenticaciónRequiere sesión OAuth del panel (cookie HttpOnly). No uses la API Key de bot en el navegador del overlay.›

Errores frecuentes

Las rutas /api/dashboard/* y /api/system/* devuelven JSON estructurado con success: false y error.message.

Respuestas de la API

Sesión expiradaCSRFExport cooldownToken inválido

	{"success": false,"error": {"message": "Sesión expirada. Por favor, vuelve a autenticarte o pide ayuda a Ponss 🦆","code": "UNAUTHORIZED"}}

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

{
"success": false,
"error": {
  "message": "Sesión expirada. Por favor, vuelve a autenticarte o pide ayuda a Ponss 🦆",
  "code": "UNAUTHORIZED"
}
}

	{"success": false,"error": {"message": "Solicitud bloqueada por protección CSRF.","code": "FORBIDDEN"}}

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

{
"success": false,
"error": {
  "message": "Solicitud bloqueada por protección CSRF.",
  "code": "FORBIDDEN"
}
}

	{"success": false,"error": {"message": "Debes esperar 3 minutos para generar otro reporte.","code": "RATE_LIMITED"}}

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

{
"success": false,
"error": {
  "message": "Debes esperar 3 minutos para generar otro reporte.",
  "code": "RATE_LIMITED"
}
}

	{"success": false,"error": {"message": "Token inválido","code": "UNAUTHORIZED"}}

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

{
"success": false,
"error": {
  "message": "Token inválido",
  "code": "UNAUTHORIZED"
}
}

Qué hacer

Escenario	Causa habitual	Solución
Sesión expirada	Token Twitch caducado o sesión muy antigua.	Cierra sesión y vuelve a Iniciar sesión con Twitch. Flujo en Inicio rápido.
CSRF al regenerar key	Pestaña abierta demasiado tiempo sin recargar.	F5 en Configuración → Seguridad y reintenta.
Export cooldown	Descargaste un reporte hace menos de 4 min.	Espera el tiempo del mensaje. Ver Perfil y seguridad.
Datos desactualizados	Caché por rol o pestaña no líder en Realtime.	Recarga la pestaña; con varias abiertas solo la líder mantiene Realtime.
Stats en cero tras limpiar	Usaste Reiniciar estadísticas (LIMPIAR).	Comportamiento esperado; Inicio y Analytics empiezan de nuevo.

1. Cierra sesión y vuelve a Iniciar sesión con Twitch en la landing.
2. Acepta el aviso de privacidad y completa OAuth.
3. Si persiste, prueba ventana privada o borra cookies de ttv.losperris.dev.

Pestaña líder

Con varias pestañas del panel, solo una mantiene Realtime (Supabase). Las demás sincronizan por BroadcastChannel. Si Realtime falla, hay polling de respaldo.

---

Overlays en OBS

Fuentes Navegador para Tendencias, Ruleta, Preguntas y similares. El overlay solo lee estado; el control está en el panel.

Solo dashboard

AutenticaciónRequiere sesión OAuth del panel (cookie HttpOnly). No uses la API Key de bot en el navegador del overlay.›

No uses la API Key en OBS

La URL del overlay lleva un overlayToken de solo lectura (30 días). No pegues tu API Key de bot en la fuente del navegador.

Token o enlace inválido

Si la URL es antigua o regeneraste la API Key, OBS puede quedar en blanco o sin datos.

Respuestas JSON

Token inválidoToken revocadoEnlace inválidoEstado vacío

	{ "error": "Token de overlay inválido o expirado." }

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

{ "error": "Token de overlay inválido o expirado." }

	{ "error": "Token de overlay revocado. Genera un enlace nuevo en el panel." }

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

{ "error": "Token de overlay revocado. Genera un enlace nuevo en el panel." }

	{"success": false,"error": {"message": "Enlace de overlay inválido o expirado.","code": "INVALID_OVERLAY_TOKEN"}}

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

{
"success": false,
"error": {
  "message": "Enlace de overlay inválido o expirado.",
  "code": "INVALID_OVERLAY_TOKEN"
}
}

	{ "state": null }

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, s-maxage=10, stale-while-revalidate
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

{ "state": null }

Escenario	Qué hacer
Token inválido / revocado	En el panel → botón Overlay → copia una URL nueva. No compartas el enlace en chat público.
state: null	Normal si el panel no ha publicado estado aún. En Tendencias, pulsa Play para iniciar.
Tras regenerar API Key	Genera enlace de overlay de nuevo; el anterior queda invalidado.

Pantalla negra o fuente congelada

1. Clic derecho en la fuente Navegador → Propiedades.
2. Pulsa Actualizar la caché de la página actual.
3. Marca Actualizar navegador cuando la escena se active.
4. Activa fondo transparente en la fuente.
5. Comprueba que la URL incluye overlayToken y fue copiada desde el panel.

Comprobaciones por herramienta

Herramienta	Comprobación	Detalle
Tendencias	Control	OBS solo refleja; pulsa Play en el panel para iniciar el temporizador.
Tendencias	Tamaño OBS	900 × 580 px (o ancho de escena).
Tendencias	Fin de sesión	Ranking final 30 s y luego el overlay se oculta (fondo transparente).
Ruleta	Estado	El panel publica el giro; OBS lee GET /dashboard/overlay-state/roulette.
Cualquiera	Caché OBS	Si cambiaste la URL, refresca la caché del navegador en OBS.

Más detalle

Configuración OBS paso a paso en Tendencias y API del overlay en la misma página.

---

Cuenta suspendida

Mensaje: Cuenta suspendida. (403)

Causa: bloqueo por abuso de límites, escaneo de claves o actividad maliciosa.

Solución: escribe en Discord con tu login de Twitch y qué endpoint usabas.

---

Checklist rápido

Problema	Primer paso
Comando silencioso	¿La URL tiene apiKey? ¿El bot usa urlfetch/customapi?
«Key inválida»	¿Regeneraste sin actualizar el bot?
429 en chat	Espera 1 min; baja frecuencia del comando.
429 en get-clips	Límite pesado 10/min; no abuses del JSON.
Overlay negro	Actualizar caché OBS + URL nueva del panel.
Panel vacío	Re-login Twitch; revisa pestaña Inicio.

---

Enlaces

Tu API KeyFormato, cabeceras y regenerar clave.

Límites de usoCuotas por rol, panel y endpoints pesados.

Perfil y seguridadGeneral, Seguridad, Conexiones y zona de peligro.

Inicio rápidoPrimer comando en el chat.