Limites de débit de l'API

Chaque requête vers https://api.primecal.eu/api est soumise à une limite de débit. Les limites dépendent de qui appelle (votre niveau) et de ce que vous appelez (la catégorie du point de terminaison).

Niveaux

Niveau	Qui l'obtient
guest	Requêtes non authentifiées
user	Utilisateurs connectés et la plupart des clés API
premium	Administrateurs système, et utilisateurs sur le forfait d'utilisation
Enterprise ou Store

Votre niveau est résolu automatiquement à partir de votre contexte d'authentification — rien à configurer. Une clé API peut aussi porter son propre niveau, indépendamment du forfait de l'utilisateur appelant.

Catégories et limites

Chaque point de terminaison appartient à une catégorie selon son chemin. Les limites sont des requêtes par fenêtre de 60 secondes, sauf indication contraire.

Catégorie	Correspond à	guest	user	premium
auth	/auth/* (à l'exclusion des chemins ci-dessous)	8	20	40
oauth	/auth/google, /auth/microsoft	60	120	240
availability	/auth/username-availability, /auth/email-availability, tout chemin /availability	30	80	180
booking	/reservations/*, /booking/*, /public-booking/*	20	120	300
admin	/admin/*	4	30	120
default	tout le reste	40	180	450

availability utilise un algorithme token-bucket (autorise de courtes rafales) ; toutes les autres catégories utilisent une fenêtre glissante.

Les limites peuvent changer sous détection d'abus

La limite effective d'une requête peut être réduite automatiquement si le système de prévention des abus de PrimeCal détecte un score de risque élevé pour votre IP/identité. Le tableau ci-dessus est la base, pas une garantie stricte à tout moment.

En-têtes de réponse

Chaque réponse — réussie ou non — inclut :

En-tête	Signification
X-RateLimit-Limit	Votre limite pour la catégorie et le niveau de cette requête
X-RateLimit-Remaining	Requêtes restantes dans la fenêtre actuelle
X-RateLimit-Reset	Horodatage Unix (secondes) de réinitialisation de la fenêtre
X-RateLimit-Policy	<algorithme>;w=<secondesFenêtre>;tier=<niveau>;category=<catégorie>

Quand vous êtes limité

Une requête dépassant la limite renvoie HTTP 429 avec un en-tête Retry-After (secondes) et un corps JSON :

{
  "statusCode": 429,
  "message": "Too many requests",
  "details": {
    "tier": "user",
    "category": "default",
    "retryAfterSeconds": 12
  }
}

Attendez au moins retryAfterSeconds avant de réessayer. Ne réessayez pas dans une boucle serrée — cela vous maintient dans la même fenêtre.

Conseils pratiques

• Regroupez et mettez en cache lorsque possible, particulièrement pour la catégorie admin — ses limites sont délibérément basses.
• Authentifiez-vous — le niveau guest est le plus restrictif dans toutes les catégories. Se connecter ou utiliser une clé API double approximativement votre budget dans la plupart des catégories.
• Un 429 ne signifie pas que quelque chose est cassé — cela signifie que vous appelez plus vite que ce que votre niveau autorise. Vérifiez X-RateLimit-Remaining avant d'atteindre zéro plutôt que de réagir après un 429.
• Si votre intégration a réellement besoin d'une limite plus élevée, les forfaits d'utilisation supérieurs (Enterprise, Store) obtiennent automatiquement le niveau premium — voir Forfaits et tarifs.

Sujets connexes

• Vue d'ensemble de l'API
• API d'authentification