Rate limits

Two limits apply to partners. One is per customer, the other covers your whole platform.

Per customer keyCopy Anchor Link

Each customer key can send up to 30 requests per minute, counted in fixed one-minute windows across every server of the API. Every request that passes authentication counts, whatever it answers: a 403 costs the same as a 200. One large customer cannot slow down the others, and you can sync several customers in parallel.

Every response, successful or not, reports the key's current window:

Beyond the limit the API answers 429 with a Retry-After header holding the seconds to wait. Pause that customer only, and continue with the others.

Failed authentication, for your whole platformCopy Anchor Link

Requests that fail authentication are counted per minute, and where they count depends on whether the request proves it is yours:

Past the limit, every request that counts against the same secret or address answers 429 Too many failed authentication attempts until the minute ends, whatever customer key it sends. A request that proves it is yours is never blocked by its address, so other traffic behind your addresses can't lock you out.

A sync that keeps retrying dead keys stops itself once it spends the 600. When a key answers 401, mark the customer disconnected and stop calling it. Fix a missing secret or an unregistered address first: those failures count against your address, with the lower limit.

When the limiter is unavailableCopy Anchor Link

The API never serves a request it cannot count. If the rate-limit store is briefly unreachable, it answers 503 Rate limiter unavailable: retry with backoff.

Stay under the limitsCopy Anchor Link

• Use limit=100 on lists. It needs half the requests of the default page size.
• Cache the catalogs once for all customers. /metrics, /prescription-types, /units, /muscles and the global part of /exercises are the same for everyone and change rarely.
• Filter on the server. Use from and userId instead of downloading everything and filtering yourself.
• Keep each customer's requests sequential, and bound how many customers you sync in parallel.

Back off on 429Copy Anchor Link

Wait Retry-After seconds, then continue where you stopped. Do not retry immediately: each retry also counts against the next window.

# curl has a built-in retry for 429, 500 and 503
curl --retry 5 --retry-all-errors \
  "https://api-integrations-next.vitruve.fit/v1/athletes" \
  -H "X-API-Key: CUSTOMER_INTEGRATION_KEY" -H "X-Partner-Secret: YOUR_PARTNER_SECRET"

async function request(path, attempt = 0) {
  const response = await fetch(`https://api-integrations-next.vitruve.fit/v1${path}`, {
    headers: { 'X-API-Key': customer.vitruveKey, 'X-Partner-Secret': process.env.VITRUVE_PARTNER_SECRET }
  })

  if (response.ok) return response.json()

  const retryable = [429, 500, 503].includes(response.status)
  if (!retryable || attempt >= 5) {
    const body = await response.json()
    throw new Error(`${response.status}: ${body.message} (request ${response.headers.get('x-request-id')})`)
  }

  const waitSeconds =
    Number(response.headers.get('retry-after')) || Math.min(2 ** attempt, 30)
  await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000))
  return request(path, attempt + 1)
}

import os
import time
import requests

def request(path, **params):
    for attempt in range(6):
        response = requests.get(
            f"https://api-integrations-next.vitruve.fit/v1{path}",
            params=params,
            headers={"X-API-Key": customer.vitruve_key, "X-Partner-Secret": os.environ["VITRUVE_PARTNER_SECRET"]},
            timeout=30,
        )
        if response.ok:
            return response.json()

        if response.status_code not in (429, 500, 503) or attempt == 5:
            request_id = response.headers.get("X-Request-Id")
            raise RuntimeError(
                f"{response.status_code}: {response.json()['message']} (request {request_id})"
            )

        wait = int(response.headers.get("Retry-After", min(2**attempt, 30)))
        time.sleep(wait)