# Autenticación y errores

> Tokens, límites de velocidad, errores e idioma de todas las APIs de Jazui.

Página original: https://docs.jazui.com/api/es

Todas las APIs de Jazui están en `https://api.jazui.com`, usan HTTPS y responden en JSON (salvo `/Render`, que devuelve HTML, y los archivos públicos del sitio). Hay cuatro grupos:

| API | Para qué | Token |
|---|---|---|
| [Render](https://docs.jazui.com/llms/es/api-render.txt) | La que usan las integraciones para pedir páginas. | Render (cuenta o sitio) |
| [Caché](https://docs.jazui.com/llms/es/api-cache.txt) | Recachear o borrar páginas desde tu despliegue o tu CMS. | Render (cuenta o sitio) |
| [Blog v2](https://docs.jazui.com/llms/es/api-blog.txt) | Leer artículos, categorías y etiquetas para pintarlos en tu web. | Público o render |
| [Archivos del sitio](https://docs.jazui.com/llms/es/api-site-files.txt) | Sitemap, robots.txt, llms.txt, Markdown para IA y visitas desde IA. | Ninguno |

Además, Jazui te avisa con [webhooks](https://docs.jazui.com/llms/es/api-webhooks.txt) cuando publicas un artículo o salta una alerta.

## Tokens

Los tokens se envían en la cabecera `Authorization` con el esquema `Bearer`. No caducan: siguen valiendo hasta que los renuevas o los revocas.

| Token | Dónde está | Sirve para | Secreto |
|---|---|---|---|
| **JAZUI Token** (render de la cuenta) | Inicio › Integración y ajustes | Render, caché y blog, para todos tus sitios. | Sí |
| **Token del sitio** | Sitios web › Token del sitio | Render, caché y blog, solo de ese sitio y sus subdominios dados de alta. | Sí |
| **PUBLIC Token** | Inicio › Integración y ajustes | Solo leer el blog. Se puede poner en el navegador. | No |

```bash
curl https://api.jazui.com/v2/cache/tasks \
  -H "Authorization: Bearer $JAZUI_TOKEN"
```

- Al **renovar** un token desde el panel, el anterior deja de valer en menos de un minuto: cambia el nuevo en tus integraciones y despliegues.
- Un token de sitio usado con otro dominio recibe un `403`.
- El PUBLIC Token no sirve para Render ni para la caché: recibe un `403` sin cuerpo.
- Si la cuenta se bloquea o se elimina, sus tokens dejan de valer.

## Límites de velocidad

| Qué | Límite | Se cuenta por |
|---|---|---|
| Render, caché y blog con token | 120 peticiones por minuto | Cuenta: todos sus tokens comparten el mismo límite |
| Feeds, archivos del sitio y lista de bots (sin token) | 120 peticiones por minuto | IP |

Al superarlo se recibe un `429` sin cuerpo. Es un límite por minuto: espera unos segundos y vuelve a intentarlo. Las integraciones lo tratan como un fallo y sirven tu web normal. No confundas este `429` con el de los límites del plan, que lleva la cabecera `X-Jazui-Limit`.

## Errores

| Código | Cuándo | Cuerpo |
|---|---|---|
| `400` | Parámetros o JSON no válidos | `{code, message}` o ProblemDetails |
| `401` | Sin token, token renovado o revocado | Vacío, con `WWW-Authenticate: Bearer` |
| `403` | El token no sirve para esa API o ese sitio, sitio sin verificar, función no incluida en el plan o bloqueo | Vacío o `{code, message}` |
| `404` | No existe o no está publicado | `{code, message}` o vacío |
| `429` | Límite de velocidad, de tareas o del plan | Vacío o `{code, message}` |
| `5xx` | Error de Jazui o de tu web al renderizar | ProblemDetails o texto, con `Retry-After` cuando conviene reintentar |

Las APIs de caché y del blog explican el error con un código estable que puedes usar en tu código y un mensaje legible:

`Error de la API de caché o del blog`:

```json
{ "code": "plan", "message": "Tu plan no incluye la API de caché." }
```

`ProblemDetails`:

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "$": ["The JSON value could not be converted."] },
  "traceId": "00-6f3c…-01"
}
```

## Idioma de los mensajes

Los mensajes de error y los textos que devuelve la API salen en español por defecto. Para recibirlos en inglés, envía `Accept-Language: en` o añade `?culture=en` a la dirección. Los códigos (`code`) no cambian con el idioma.

## Sin token

Algunas direcciones son públicas: la lista de bots que usan las integraciones, el estado del servicio, los feeds del blog y los archivos de cada sitio verificado.

```bash
# Lista de bots que usan las integraciones (JSON y texto)
curl https://api.jazui.com/v2/bots
curl https://api.jazui.com/v2/bots.txt

# Bloques listos para nginx, IIS y Apache
curl https://api.jazui.com/v2/bots/config

# Estado del servicio
curl https://api.jazui.com/health
```