- Documentation
- API · Version 1.0
- Limites et conventions
Limites et conventions
Sur cette page
Ce que l'API limite, et les conventions qu'elle suit sur toutes ses routes : débit, pagination, identifiants, dates et quotas.
Limites de débit
Deux limites, qui ne mesurent pas la même chose :
| Limite | Défaut | Compte |
|---|---|---|
| Par adresse IP | 300 requêtes par minute | Toutes les requêtes, y compris celles qui échouent à l'authentification. |
| Par client d'API | 120 requêtes par minute | Les requêtes authentifiées de ce client, quelle que soit l'adresse d'où elles partent. |
La première protège d'un balayage d'identifiants, qui n'appartient à aucun client ; la seconde, d'une intégration qui s'emballe.
Une réponse authentifiée porte les en-têtes de la limite du client :
| En-tête | Sens |
|---|---|
X-RateLimit-Limit |
Le nombre de requêtes permises par minute. |
X-RateLimit-Remaining |
Ce qu'il en reste dans la minute en cours. |
Au-delà de l'une ou l'autre, l'API répond 429 :
{
"error": {
"code": "too_many_requests",
"message": "Too many requests. Retry after the delay given by the Retry-After header."
}
}
La réponse porte alors Retry-After (en secondes), X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (horodatage Unix de la remise à zéro) de la limite atteinte. Attendez le délai de Retry-After avant de reprendre, et surveillez X-RateLimit-Remaining sur les réponses réussies pour ralentir avant d'être arrêté. Une requête refusée par la limite du client n'est pas comptée dans la consommation de l'espace.
La notification de contrôle d'un webhook a sa propre limite : 5 par minute et par endpoint (voir Webhooks).
Pagination
GET /destinations, GET /publications et GET /media sont paginées. per_page vaut 25 par défaut et est borné entre 1 et 100. GET /brands et GET /webhooks rendent la liste complète.
Les trois listes paginées acceptent aussi brand_id : un client qui couvre tout l'espace de travail y lit une seule marque. Une marque hors de portée du client rend une liste vide, sans erreur.
Une réponse paginée porte trois clés : data, links et meta.
{
"data": ["…"],
"links": {
"first": "https://quietsocial.dev/api/v1/publications?page=1",
"last": "https://quietsocial.dev/api/v1/publications?page=3",
"prev": null,
"next": "https://quietsocial.dev/api/v1/publications?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 3,
"links": ["…"],
"path": "https://quietsocial.dev/api/v1/publications",
"per_page": 25,
"to": 25,
"total": 61
}
}
Paginez en suivant links.next jusqu'à ce qu'il vaille null. Les paramètres de la requête — filtres compris — sont conservés dans ces liens. meta.links sert à afficher une pagination ; ses libellés ne font pas partie du contrat.
Identifiants
L'API n'expose jamais de numéro séquentiel : il se devinerait, et laisserait sonder les ressources d'un autre espace. Chaque ressource porte un identifiant public, préfixé et immuable :
| Préfixe | Ressource |
|---|---|
qsc_ |
Client d'API |
brd_ |
Marque |
dst_ |
Destination |
pub_ |
Publication |
med_ |
Média |
whe_ |
Endpoint de webhook |
whd_ |
Livraison de webhook |
Après le préfixe vient une suite de caractères en minuscules (pub_01k4b8y5t2v9h6p8w0y2z4b6c8). Traitez l'identifiant comme une chaîne opaque, et n'en déduisez rien.
Dates et fuseaux
Les dates rendues sont en ISO 8601 avec leur décalage, en UTC. Les dates envoyées doivent suivre ISO 8601 et peuvent porter n'importe quel décalage : 2026-10-02T08:00:00+02:00 et 2026-10-02T06:00:00Z désignent le même instant. Sans décalage, l'heure est lue en UTC ; toute autre forme est refusée en 422.
timezone (fuseau IANA, Europe/Paris) accompagne une publication ; il est celui de la marque par défaut.
Quotas
Une marque peut avoir deux plafonds mensuels, lisibles dans GET /brands :
monthly_publication_limit— publications créées dans le mois. Au-delà, la création répond422 publication_not_publishable.monthly_delivery_limit— livraisons réussies sur un réseau dans le mois. Il est vérifié quand une publication retenue est libérée parpublish:409 transition_not_allowedsi les cibles à libérer dépassent ce qui reste.
null signifie « sans plafond ». Les compteurs repartent de zéro le premier de chaque mois, à minuit UTC.
Ce que l'API ne fait pas
- Elle ne crée ni connexion, ni destination, ni marque : cela se fait dans le tableau de bord.
- Elle ne valide pas une publication soumise à validation ; seule l'équipe le fait, dans le tableau de bord.
- Elle ne rend pas d'adresse de téléchargement des médias.