Anfragen, Paginierung und Limits

JSON-Envelopes

Erfolgreiche Antworten für Einzelressourcen verwenden folgende Struktur:

{ "data": {}, "request_id": "req_example" }

Listen enthalten zusätzliche Paginierungsfelder:

{
  "data": [],
  "has_more": true,
  "next_cursor": "opaque-cursor",
  "request_id": "req_example"
}

Unbekannte Eigenschaften im JSON-Body werden mit unknown_field abgewiesen. So fallen Tippfehler bei Schreiboperationen direkt auf, anstatt stillschweigend ignoriert zu werden.

Bei Query-Parametern verhält es sich anders: Unbekannte Parameter werden ignoriert und nicht abgewiesen. Da Analyse-Tools und Proxys häufig eigene Parameter anhängen (utm_*, cf_*), würde das Ablehnen einer ansonsten gültigen Anfrage zu unnötigen Fehlern führen.

Standardwerte

Die Standardwerte sind für eine sichere interaktive Nutzung ausgelegt. Beispielsweise bezieht sich die Nutzungsstatistik standardmäßig auf die letzten 30 Tage und bei Übersetzungen werden standardmäßig die letzten 25 nicht archivierten Einträge zurückgegeben. Wird ein Listenlimit von über 100 angefordert, wird dieses auf 100 begrenzt.

Datums- und Zeitangaben folgen ISO 8601. JSON-Feldnamen sind in snake_case formatiert. Noch nicht zutreffende Felder sind in der Regel null, damit die Datenstruktur über den gesamten Lebenszyklus einer Übersetzung hinweg stabil bleibt.

Cursor-Paginierung

Übergeben Sie next_cursor aus einer Antwort unverändert an die nachfolgende Anfrage. Brechen Sie ab, sobald der Wert null ist oder has_more auf false steht.

let cursor;
do {
  const url = new URL('https://api.ai-glot.com/v1/batches');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const page = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.AIGLOT_API_KEY}` },
  }).then(response => response.json());

  for (const translation of page.data) console.log(translation.id);
  cursor = page.next_cursor;
} while (cursor);

Erstellen oder manipulieren Sie Cursors nicht manuell. Die Cursor-Paginierung verhindert, dass neu erstellte Übersetzungen die Zeilenanordnung über verschiedene Seiten hinweg verschieben.

Rate-Limits

Für alle Zugangsdaten gilt ein Dauerlimit von 240 Anfragen pro Minute sowie ein Burst-Limit von 40 Anfragen pro 10 Sekunden. Eine 429-Antwort enthält den Header Retry-After; warten Sie diese Zeitspanne ab, bevor Sie den Vorgang wiederholen.

Jede Antwort enthält einen RateLimit-Policy-Header, der beide Zeitfenster beschreibt:

RateLimit-Policy: 240;w=60, 40;w=10

Dieser Header gibt ausschließlich die Richtlinie an. Es wird keine verbleibende Anzahl an Anfragen übermittelt; orientieren Sie Ihre Anfragen daher an den dokumentierten Limits und nutzen Sie 429 zusammen mit Retry-After als Signal zur Drosselung (Backoff).

Request-IDs und Retries

Jede Antwort enthält eine Request-ID sowohl im Payload (request_id) als auch im X-Request-Id-Header. Geben Sie diese bei Support-Anfragen bitte an.

Wiederholen Sie Anfragen bei den Statuscodes 429, 500, 502, 503 und 504 mit exponentiellem Backoff und Jitter. Fehler bei der Validierung, Authentifizierung, Berechtigung oder Not-Found-Fehler sollten nicht ohne vorherige Änderung der Anfrage wiederholt werden.

Abschließende Schrägstriche (Trailing Slashes) werden toleriert. Die REST-API sendet bewusst keine CORS-Berechtigungsheader für Browser, da Workspace-Zugangsdaten ausschließlich in vertrauenswürdigem serverseitigem Code verwendet werden sollten.