Límites de tasa

Cada endpoint de la API de Genius Checkout pertenece a uno de tres tiers. Los límites son por API key (por comercio para tráfico autenticado, por IP para tráfico no autenticado) y se renuevan con una ventana móvil de un minuto.

Tiers

Tier	Límite	Cubre
payment-mutations	60 / minuto	Escrituras que mueven dinero — crear pago, reembolso, captura, anulación, tokenize, charge-token, crear suscripción, cancelar suscripción, desactivar token
writes	120 / minuto	Lecturas + escrituras no monetarias — listar/obtener cualquier recurso, crear/pausar/archivar payment link, pausar/reanudar suscripción, Zapier subscribe/unsubscribe
public-reads	300 / minuto	Lecturas no autenticadas (hoy solo usado por renderizado público de payment links)

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

Encabezados de respuesta

Cada respuesta autenticada lleva:

Encabezado	Significado
X-RateLimit-Limit	Máximo de solicitudes en la ventana actual para este tier
X-RateLimit-Remaining	Solicitudes restantes antes del próximo 429

Cuando excedes el límite, el 429 agrega:

Encabezado	Significado
Retry-After	Segundos hasta que la ventana se reinicia

Cuerpo de 429

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

retry_after coincide con el encabezado Retry-After en segundos.

Guía de backoff

• Honra siempre Retry-After — no encuestes con más frecuencia.
• Usa backoff exponencial con jitter si no puedes leer el encabezado: min(60s, base * 2^n + random(0, 1s)) empezando con base = 1s.
• Para jobs en lote (reembolsos masivos, recargos masivos), mantente bajo 50/min en payment-mutations para dejar margen al tráfico simultáneo.
• Usa Idempotency-Key en cada reintento para volver a enviar sin riesgo de doble cobro.

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 — mismo patrón con `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

Holgura para ráfagas

Los límites se evalúan por clave. Dividir tráfico entre múltiples API keys no es una manera sancionada de multiplicar tu límite efectivo — si necesitas más throughput en una sola cuenta, contacta soporte y podemos subir el tier de tu clave.

Siguiente

• Manejo de errores — tabla completa de códigos de estado
• Idempotencia — reintentos seguros en 429 y 5xx