Help Center / api

Ratenbegrenzungen

Unsere API verwendet Ratenbegrenzungen, um eine faire Nutzung und Stabilität zu gewährleisten. Erfahren Sie, wie die Begrenzungen funktionieren und wie Sie damit umgehen.

So funktioniert die Begrenzung

OSIR verkauft keine API-Tarifstufen. Begrenzungen gibt es nur, damit ein einzelner Aufrufer die anderen nicht aushungert, und sie sind für automatisierte Clients bewusst grosszügig.

Die Kontingente füllen sich laufend wieder auf, statt zu einem festen Zeitpunkt zurückgesetzt zu werden; ein Burst, der das Limit erreicht, erholt sich daher innerhalb von Sekunden. Health-Checks werden nie begrenzt.

Zwei Abläufe haben eigene Begrenzungen: KI-Chat-Relay 150/Minute sowie Kontoregistrierung 50/Tag pro IP und 3/Tag pro E-Mail-Adresse.

Header für Ratenbegrenzungen

Antworten enthalten einen Header:

x-ratelimit-remaining: 149

Ein 429 enthält zusätzlich Retry-After und X-RateLimit-Retry-After, beide in Sekunden.

Lesen Sie x-ratelimit-remaining bei jeder Antwort und drosseln Sie, wenn er sich null nähert. X-RateLimit-Limit und X-RateLimit-Reset werden nicht gesendet; bauen Sie keine Logik darauf auf.

Für automatisierte Clients

Verfügbarkeitsergebnisse werden kurz zwischengespeichert, sodass wiederholte Prüfungen desselben Namens die Registry nie erreichen. Alles, was Geld bewegt, akzeptiert einen Idempotency-Key, sodass ein erneuter Versuch nach einem 429 oder einem Timeout keine doppelte Belastung auslösen kann.

Mit Ratenbegrenzungen umgehen

Header prüfen

const response = await fetch('https://be.osir.com/v1/public/catalog/domains/example.com/availability')
const remaining = response.headers.get('x-ratelimit-remaining')

if (remaining < 10) {
  // Anfragen verlangsamen
}

429-Fehler behandeln

async function fetchWithRetry(url, options, retries = 3) {
  const response = await fetch(url, options)

  if (response.status === 429 && retries > 0) {
    const retryAfter = response.headers.get('Retry-After') || 60
    await sleep(retryAfter * 1000)
    return fetchWithRetry(url, options, retries - 1)
  }

  return response
}

429-Antwort

Bei Erreichen der Ratenbegrenzung. Beachten Sie den Retry-After-Header: ein sofortiger erneuter Versuch verbraucht Kontingent, das Sie nicht haben.

{
  "error": "Rate limit exceeded",
  "retryAfterSeconds": 42
}

Bewährte Vorgehensweisen

1. Exponentielles Backoff implementieren

async function backoff(attempt) {
  const delay = Math.min(1000 * Math.pow(2, attempt), 30000)
  await sleep(delay)
}

2. Caching verwenden

// Antworten zwischenspeichern, die sich selten ändern
const cache = new Map()
const CACHE_TTL = 60000 // 1 Minute

async function getCachedDomains() {
  if (cache.has('domains') && cache.get('domains').expires > Date.now()) {
    return cache.get('domains').data
  }

  const data = await fetchDomains()
  cache.set('domains', { data, expires: Date.now() + CACHE_TTL })
  return data
}

3. Anfragen bündeln

Anstelle von:

// Schlecht: 100 Anfragen
for (const domain of domains) {
  await checkDomain(domain)
}

Verwenden Sie:

// Gut: 1 Anfrage
await checkDomains(domains) // Massen-Endpunkt

Begrenzungen erhöhen

Benötigen Sie höhere Begrenzungen?

Wenden Sie sich an den Support und beschreiben Sie Ihren Anwendungsfall.