Limites de débit

Chaque endpoint de l'API Genius Checkout est dans l'un de trois tiers. Les limites sont par clé API (par marchand pour le trafic authentifié, par IP pour le non authentifié) et se renouvellent sur une fenêtre glissante d'une minute.

Tiers

Tier	Limite	Couvre
payment-mutations	60 / minute	Écritures qui déplacent de l'argent — créer un paiement, remboursement, capture, annulation, tokenize, charge-token, créer un abonnement, annuler un abonnement, désactiver un token
writes	120 / minute	Lectures + écritures non monétaires — list/get de toute ressource, créer/pause/archiver payment link, pause/reprendre abonnement, Zapier subscribe/unsubscribe
public-reads	300 / minute	Lectures non authentifiées (uniquement le rendu public des payment links aujourd'hui)

Endpoint → tier

Endpoint	Tier
POST /payments, POST /payments/{id}/capture, POST /payments/{id}/refund, POST /payments/{id}/void	payment-mutations
GET /payments/{id}	writes
POST /checkout-sessions	writes
GET /checkout-sessions/{id}	writes
POST /tokenize, POST /charge-token	payment-mutations
POST /subscriptions, POST /subscriptions/{id}/cancel	payment-mutations
GET /subscriptions, GET /subscriptions/{id}, POST /subscriptions/{id}/pause, POST /subscriptions/{id}/resume, PUT /subscriptions/{id}/payment-method	writes
GET /transactions, GET /customers, GET /customers/{id}/payment-tokens	writes
POST /payment-tokens/{id}/deactivate	payment-mutations
GET /payment-links, POST /payment-links, GET /payment-links/{id}, POST /payment-links/{id}/*	writes
POST /zapier/subscriptions, DELETE /zapier/subscriptions/{id}, GET /zapier/sample-payments	writes

En-têtes de réponse

Chaque réponse authentifiée porte :

En-tête	Signification
X-RateLimit-Limit	Maximum de requêtes dans la fenêtre courante pour ce tier
X-RateLimit-Remaining	Requêtes restantes avant le prochain 429

Quand vous dépassez la limite, le 429 ajoute :

En-tête	Signification
Retry-After	Secondes jusqu'au reset de la fenêtre

Corps 429

{
  "error": "Too many requests. Please try again later.",
  "retry_after": 17
}

retry_after correspond à l'en-tête Retry-After en secondes.

Conseils de backoff

• Honorez toujours Retry-After — ne sondez pas plus fort.
• Utilisez un backoff exponentiel avec jitter si vous ne pouvez pas lire l'en-tête : min(60s, base * 2^n + random(0, 1s)) en partant de base = 1s.
• Pour les jobs batch (remboursements en masse, re-débits en masse), restez sous 50/min sur payment-mutations pour laisser de la marge au trafic simultané.
• Utilisez Idempotency-Key sur chaque retry pour pouvoir relancer une requête sans double-débit.

async function callWithBackoff(url, init, attempt = 0) {
  const res = await fetch(url, init)
  if (res.status !== 429) return res
  const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt
  await new Promise(r => setTimeout(r, wait * 1000))
  return callWithBackoff(url, init, attempt + 1)
}

# Python — même pattern avec `requests`
import requests, time
def call_with_backoff(method, url, **kwargs):
    for attempt in range(6):
        r = requests.request(method, url, **kwargs)
        if r.status_code != 429:
            return r
        wait = int(r.headers.get('Retry-After', 2 ** attempt))
        time.sleep(wait)
    return r

Marge pour les pics

Les limites sont évaluées par clé. Répartir le trafic sur plusieurs clés API n'est pas une manière sanctionnée de multiplier votre limite — si vous avez besoin de plus de débit sur un seul compte marchand, contactez le support et nous pouvons relever le tier de votre clé.

Suite

• Gestion des erreurs — table complète des codes de statut
• Idempotence — relances sûres en 429 et 5xx