Rate limits

VINR throttles API traffic to keep the platform fast and fair for every merchant. This page explains the per-environment limits, the headers that let you track your budget in real time, and how to back off cleanly when you hit a 429 Too Many Requests.

How limiting worksAskCopy

Limits are enforced per secret key using a token-bucket algorithm. Each bucket refills continuously at a fixed rate and holds a burst allowance on top, so short spikes are absorbed while sustained overuse is throttled. Read and write operations share the same key but are metered in separate buckets — a flood of GET /payments calls will not consume your capacity to create payments.

Limits by environmentAskCopy

Webhook delivery, hosted checkout sessions, and the dashboard are not counted against your API budget. Bulk endpoints such as list operations return up to 100 objects per page; paginate with the starting_after cursor rather than polling a single page in a tight loop.

Rate-limit headersAskCopy

Every response includes headers describing your current budget. Read them on success as well as on 429, so you can throttle proactively instead of reacting to errors.

A throttled response uses status 429 with a structured body:

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_requests",
    "message": "Request rate exceeded. Retry after 2 seconds.",
    "retry_after": 2
  }
}

Backoff strategyAskCopy

When you receive a 429, wait at least the number of seconds in Retry-After, then retry with exponential backoff and jitter. Jitter prevents many clients from retrying in lockstep and re-triggering the limit. The SDK applies this automatically for idempotent operations, but here is the logic if you call the REST API directly.

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({
  secretKey: process.env.VINR_SECRET_KEY,
  maxRetries: 5,        // attempts after the initial request
  retryBaseDelayMs: 250 // grows exponentially with jitter, capped at Retry-After
});

// No special handling needed — throttled calls are retried for you.
const payment = await vinr.payments.create({
  amount: 1000,
  currency: 'EUR',
  returnUrl: 'https://shop.example.com/return',
});

async function callWithBackoff(path: string, init: RequestInit, attempt = 0): Promise<Response> {
  const res = await fetch(`https://api.vinr.com/v1${path}`, {
    ...init,
    headers: { 'X-Api-Key': process.env.VINR_SECRET_KEY!, ...init.headers },
  });

  if (res.status !== 429 || attempt >= 5) return res;

  const retryAfter = Number(res.headers.get('Retry-After') ?? 1);
  const backoff = Math.min(2 ** attempt * 250, retryAfter * 1000);
  const jitter = Math.random() * backoff;
  await new Promise((r) => setTimeout(r, backoff + jitter));

  return callWithBackoff(path, init, attempt + 1);
}

Staying under the limitAskCopy

Next stepsAskCopy