Quotas et limites

Limites de débit

• 60 requêtes par minute et par clé. Chaque réponse porte les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (instant de fin de la fenêtre, en secondes Unix).
• Une limite par adresse IP s'applique avant la lecture de la clé (120 requêtes par minute) : des clients hébergés qui partagent une adresse peuvent la voir se déclencher.
• Au-delà, la réponse est un 429 avec un en-tête Retry-After (secondes à attendre). Ces valeurs sont des valeurs de départ : elles pourront être ajustées après les premiers usages.

Protection du service

L'API partage sa base avec l'application de PublikConnect : quelques garde-fous protègent les deux. Aucun ne demande de réglage de votre part, mais votre client doit les connaître.

Identifiant de requête : X-Request-Id

Toute réponse de l'API porte un en-tête X-Request-Id (une valeur unique par requête), erreurs 401, 403, 429 et 503 comprises. Il est généré par PublikConnect : un X-Request-Id que vous envoyez n'est pas repris. Citez-le au support pour qu'on retrouve votre requête dans les journaux. Seul le document /openapi.json, statique, n'en porte pas.

Requêtes simultanées

Une clé peut avoir 4 requêtes en cours au plus, et l'API en traite 8 au plus pour toutes les clés ensemble. Au-delà, la réponse est un 503 de code unavailable avec Retry-After: 1 : rien n'est traité et aucun quota n'est réservé. Réessayez une seconde plus tard et, dans un script, limitez-vous à quelques appels en parallèle. Les autres 503 portent Retry-After: 30. /sante et /openapi.json ne sont pas comptés. Ces plafonds sont tenus par instance du service et peuvent évoluer.

Fraîcheur des données

La liste GET /avis en mode page (et l'outil MCP search_avis), GET /avis en mode curseur sans updated_since, GET /departements et GET /sources sont gardées en mémoire 60 secondes : deux requêtes identiques dans la minute reçoivent la même réponse, qui peut donc dater d'une minute au plus. La reprise des changements (GET /avis?updated_since=…) n'est jamais gardée en mémoire. Une réponse servie ainsi compte dans le quota exactement comme une réponse calculée. Couper une source du registre se voit au plus tard une minute plus tard. GET /attributions et GET /contrats sont gardées 60 secondes de la même façon (la clé de mise en mémoire contient tous les filtres et le curseur). GET /opportunites, GET /avis/{id}, GET /prestataires, GET /prestataires/{slug}, GET /acheteurs/{siret} et GET /moi ne sont jamais gardées en mémoire.

Délais et coupures

Une requête à la base qui dépasse son délai (5 secondes pour les listes) répond 503 de code unavailable, sans rien compter dans votre quota. L'équipe peut aussi couper l'API entière, ou une seule ressource (avis, opportunités, prestataires, acheteurs, attributions, contrats, départements, compte ; GET /sources suit la ressource avis) : les routes concernées répondent 503 et les autres continuent. Dans le serveur MCP, les outils d'une ressource coupée disparaissent de la liste.

Quota journalier

En plus de la limite de débit, chaque compte a un quota journalier d'enregistrements servis.

• Unité : l'enregistrement (un avis d'une liste, un avis en détail, un prestataire d'une liste, une fiche prestataire, une fiche acheteur), pas la requête. Une page de 100 avis coûte 100 ; une page qui n'en contient que 3 en coûte 3.
• Par compte : toutes les clés d'un même compte partagent le même quota. Une clé de plus n'en donne pas davantage.
• Deux familles, chacune avec sa limite : general (les avis, les opportunités, les fiches prestataires et les fiches acheteurs) : 50 000 par jour par défaut ; decp (/contrats et /attributions, périmètre decp:read) : 2 000 par jour par défaut. L'équipe PublikConnect peut les relever ou les abaisser pour un compte.
• Jour UTC : le compteur repart de zéro à minuit UTC (2 h du matin en été en France, 1 h en hiver).
• Strict : la limite est tenue en base, deux requêtes simultanées ne peuvent pas la dépasser. Avant de répondre, le service réserve per_page enregistrements pour une liste (limite pour /attributions et /contrats ; 1 pour un détail ou une fiche). Une réserve refusée donne un 429, sans rien renvoyer. Après la réponse, la part réservée mais non servie est rendue. Conséquence : avec per_page=100, il faut au moins 100 enregistrements disponibles pour être servi, même si la page n'en contient que 3. Pour utiliser le quota jusqu'au bout, baissez per_page.
• Ce qui est compté : les enregistrements servis (réponses 200). En synchronisation, un avis retiré compte comme un enregistrement servi. Une réponse d'erreur (400, 404, 503) ne consomme rien, mais la requête est enregistrée dans les statistiques d'usage. GET /departements, GET /sources et GET /moi ne consomment aucun quota. GET /openapi.json n'est pas compté.
• Dépassement : 429 avec le code quota_exceeded, un Retry-After en secondes jusqu'à minuit UTC, et X-Quota-Remaining: 0. Le message est fixe : Quota journalier atteint. Il se renouvelle à minuit UTC.
• En-têtes : toute réponse d'une route qui réserve du quota (/avis, /avis/{id}, /opportunites, /prestataires, /prestataires/{slug}, /acheteurs/{siret}, /attributions, /contrats), erreurs comprises, porte X-Quota-Limit (limite journalière de la famille) et X-Quota-Remaining (enregistrements restants aujourd'hui, réserve non servie rendue ; jamais négatif).
• Panne : si le quota ne peut pas être vérifié (base indisponible), la réponse est un 503, rien n'est servi. Si l'enregistrement de la consommation échoue après la réponse, la réserve reste comptée : l'erreur va toujours dans le sens de la limite.

GET /moi donne l'état du quota à tout moment. Le serveur MCP applique les mêmes règles à ses outils (voir le serveur MCP).