# Limites de Débit & Cache Redis

## 🚦 Niveaux d'accès

L'API n'a pas de clé : trois niveaux d'accès se distinguent par un secret partagé entre les serveurs de CLAIR (`CLAIR_INTERNAL_SECRET`, envoyé dans l'en-tête `x-clair-internal`), qui ne quitte jamais ces serveurs.

| Niveau | Qui | Limite |
| :--- | :--- | :--- |
| Anonyme | Tout appel direct à `api.clair.vote` : scripts, réutilisateurs, intégrations | **10 requêtes par minute** et par IP |
| Navigateur relayé | Visiteur de clair.vote : ses appels passent par le proxy Next `/api/v1/[...path]`, qui ajoute le secret et l'IP du visiteur (`x-clair-client-ip`) | 60 requêtes par minute et par IP de visiteur |
| Interne | Rendu serveur du site, sitemap, ingestion (secret, sans IP de visiteur) | Aucune |

Règles supplémentaires pour le niveau anonyme :

- **User-Agent** : les User-Agent `node` et `undici` exacts sont refusés (403). Identifiez votre client par un User-Agent descriptif, par exemple `MonProjet/1.0 (contact@exemple.org)`.
- **Blocage temporaire** : 30 réponses 429 en 5 minutes entraînent un blocage de l'IP pendant 1 heure.

Les routes `/health` sont exclues de la limitation. Pour un usage intensif de l'API : [contact@clair.vote](mailto:contact@clair.vote).

`POST /api/v1/homepage/warm` (invalidation du cache de la page d'accueil, appelée par l'ingestion en fin de batch) n'accepte que le niveau interne **sans** IP de visiteur : une requête relayée par le site reçoit un 403, comme toute requête sans le secret. La spécification OpenAPI déclare ce jeton (`x-clair-internal`) sur cette route ; il n'est pas délivré.

---

## ⚡ Cache Redis

Chaque route met sa réponse en cache avec une durée de vie propre :

| Module | Durée de vie |
| :--- | :--- |
| Page d'accueil | 27 h (bloc « à venir » : 15 min) |
| Parlementaires | 1 h, 12 h ou 24 h selon la route |
| Scrutins | 1 h (liste) ; 12 h (tags, scrutins importants) ; 24 h (années, périodes) |
| Dossiers | 1 h |
| Sujets | 1 h ; 12 h (sujets mis en avant, catégories) ; presse : 3 h, ou 15 min si le flux est vide |
| Groupes | 1 h ou 12 h selon la route |
| Commissions | 12 h ; 1 h pour ce qui dépend des réunions |
| Agenda | 1 h |
| Sénatoriales | 1 h ; résultats : 1 min |
| Lobbying, analytics | 12 h |
| Sitemap | 24 h |

Le batch nocturne ne reconstruit que la page d'accueil (voir [Orchestrateur d'ingestion](/donnees/orchestrateur-ingestion)) ; les autres entrées expirent d'elles-mêmes. Après une correction massive de données, il faut purger les clés concernées dans Redis pour qu'elle soit visible immédiatement.

Au démarrage en production, l'API préchauffe une à une quelques routes : page d'accueil, premières pages de députés, de sénateurs et de scrutins, groupes des deux chambres, statistiques et secteurs du lobbying, première page des lobbyistes.