Limites de Taux

Audience

Cette surface d'API est destinée aux partenaires d'intégration construisant sur le réseau Rokt. Les partenaires e-commerce de Rokt intégrant des emplacements sur leur propre page de paiement devraient utiliser à la place les documents développeur de Rokt Ecommerce.

L'API des Partenariats limite les requêtes par minute sur un petit ensemble de points de terminaison à forte écriture et de récupération. Les limites sont associées à votre partenaire principal (dérivé de votre jeton API), et non à votre IP, donc plusieurs serveurs dans votre flotte partagent un même seau.

Limites par point de terminaisonLien direct vers Limites par point de terminaison

Méthode & Chemin	Limite	Raisonnement
`POST /v1/accounts/register/partnership`	10 / minute	L'enregistrement déclenche une orchestration backend en plusieurs étapes ; c'est coûteux, et le trafic d'intégration des marchands est plus en rafales que soutenu.
`POST /v1/partnership/accounts/{account_id}/payout-setup`	10 / minute	Chaque appel provisionne un compte Stripe Connect.
`POST /v1/partnership/network-privacy-requests`	10 / minute	Le trafic de demandes de confidentialité des consommateurs doit être rythmé et soumis une fois par demande d'utilisateur.
`POST /v1/partnership/accounts/{account_id}/data-deletion-requests`	10 / minute	La suppression au niveau du compte est soumise au service de suppression de données et est suivie en tant qu'opération de partenariat.
`POST /v1/partnership/accounts/{account_id}/pages`	30 / minute	La fourniture de pages supplémentaires est plus lourde qu'une écriture de contrôles ; plafond inférieur à MCL/status.
`PUT /v1/partnership/accounts/{account_id}/pages/{page_id}`	30 / minute	Le changement de type de mise en page est un travail de fourniture de pages : même catégorie de poids et plafond que l'ajout de pages.
`PATCH /v1/partnership/accounts/{account_id}/layouts/{layout_id}`	60 / minute	Le PATCH de thème écrit la configuration de mise en page modélisée.
`PUT /v1/partnership/accounts/{account_id}/marketplacecontrolslists`	60 / minute	Écritures de contrôle par marchand ; marge de manœuvre confortable pour la synchronisation par lots.
`PUT /v1/partnership/accounts/{account_id}/offercontrolslists`	60 / minute	Écritures de contrôle côté offre par marchand.
`PUT /v1/partnership/accounts/{account_id}/status`	60 / minute	Pause/reprise en cascade à travers les variantes de pages.
`GET /v1/partnership/operations/{operation_id}`	600 / minute	Adapté au polling. Dimensionné pour ~10 sondages/sec à travers toute votre flotte.
Autres points de terminaison de lecture (`GET /v1/partnership/accounts`, MCL, OCL, status, payout-status, blocked-domains)	60 / minute	Par défaut par partenaire pour les lectures de partenariat.

info

Les limites sont par partenaire, pas par marchand. Si vous intégrez 50 marchands en une minute, vous atteindrez la limite d'enregistrement au 11ème appel, quel que soit le marchand concerné. Échelonnez les rafales ou mettez en file d'attente côté client.

remarque

POST /v1/partnership/network-privacy-requests ne prend pas Idempotency-Key et ne crée pas d'opération de partenariat. Pour ce point de terminaison, respectez Retry-After et réessayez uniquement la même demande utilisateur après temporisation. La suppression de données au niveau du compte utilise le contrat de réessai normal Idempotency-Key.

Comment les limites sont associéesLien direct vers Comment les limites sont associées

Les limites sont associées à vos identifiants API. Chaque serveur de votre flotte utilisant les mêmes identifiants partage un compteur unique.

Les requêtes avec un en-tête Authorization manquant, invalide ou non vérifiable sont rejetées avec un 401 avant que la limitation de taux ne s'applique.

La réponse 429Lien direct vers La réponse 429

Lorsqu'une limite est dépassée, le serveur renvoie 429 Too Many Requests avec l'enveloppe standard de partenariat :

{
  "status": 429,
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded: 10 per 1 minute. Retry after the window resets.",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": null
}

En-têtes de réponseLien direct vers En-têtes de réponse

Une réponse 429 contient :

Retry-Afterinteger

Secondes jusqu'à ce que le prochain appel soit accepté. Respectez cela ; c'est le signal le moins coûteux que vous ayez.

Backoff guidanceLien direct vers Backoff guidance

Respecter d'abord Retry-After
En cas de 429, attendez la valeur de Retry-After avant toute nouvelle tentative. Elle est déjà calculée à partir de votre fenêtre restante. Il n'y a aucun avantage à réessayer plus tôt, et les nouvelles tentatives à l'intérieur de la fenêtre comptent pour votre quota.
Utiliser la même Idempotency-Key lors de la nouvelle tentative
Pour les appels POST et PUT, réessayez avec la même Idempotency-Key que celle utilisée lors de l'appel rejeté, à l'intérieur de la fenêtre de déduplication de 24 heures. Les rejets dus aux limites de taux ne s'exécutent pas côté serveur, donc la réponse mise en cache sera le succès éventuel, et non un 429 obsolète.
Limiter la concurrence côté client
Faites la queue côté client et respectez Retry-After ; anticiper la limite est moins coûteux que d'y réagir.
Sondage : rythmer vos lectures d'opérations
La limite de 600/min sur le sondage d'opérations est dimensionnée pour un sondage toutes les ~100ms sur l'ensemble de votre flotte. Si vous sondez plus fréquemment, vous payez un coût de sortie pour aucune information ; les opérations ne changent pas aussi rapidement. Recommandation : sondez toutes les 2 à 5 secondes avec un backoff exponentiel jusqu'à 60 secondes.

attention

Ne réessayez pas avec une nouvelle Idempotency-Key après un 429. L'appel original n'a pas été exécuté, mais si vous envoyez plus tard une clé différente pour la même écriture logique, le serveur n'a aucun moyen de dédupliquer, et vous pourriez vous retrouver avec un état dupliqué si une nouvelle tentative réussit deux fois pour des raisons différentes.

Ce qui n'est pas limité en taux (aujourd'hui)Lien direct vers Ce qui n'est pas limité en taux (aujourd'hui)

Les points de terminaison GET autres que le sondage d'opérations (y compris les lectures de contrôles, les lectures de statut et les lectures de statut de paiement) ne sont pas limités en taux aujourd'hui. Cela peut changer. Considérez l'absence de limite documentée comme "actuellement non plafonnée" plutôt que "garantie non plafonnée".

Quand vous avez réellement besoin de limites plus élevéesLien direct vers Quand vous avez réellement besoin de limites plus élevées

Les plafonds actuels sont dimensionnés pour le trafic d'intégration des marchands en régime permanent. Si votre plan de lancement prévoit un pic soutenu (par exemple, remplir 10 000 marchands dans une seule fenêtre de migration), envoyez un email à smb-partnerships@rokt.com avec le point de terminaison, le RPS attendu et la fenêtre de durée. Nous pouvons augmenter le plafond de votre partenaire principal à l'avance sans modification de code de votre côté.

Erreurs : référence complète des codes de statut, y compris la place du 429 dans l'enveloppe
Idempotence : comment la fenêtre de déduplication interagit avec les nouvelles tentatives
Gestion des échecs : politique de nouvelle tentative plus large pour toutes les classes d'erreurs