Anfragen, Paginierung und Limits

JSON-Envelopes

Erfolgreiche Antworten für einzelne Ressourcen nutzen folgendes Format:

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

Listen ergänzen dies um Paginierungsfelder:

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

Unbekannte Eigenschaften im JSON-Body werden mit unknown_field abgelehnt. So wird ein Tippfehler bei einer Schreiboperation erkannt, anstatt ihn stillschweigend zu ignorieren.

Query-Parameter verhalten sich anders: Unbekannte Parameter werden ignoriert, nicht abgelehnt. Analyse-Tools und Proxys fügen routinemäßig eigene Parameter hinzu (utm_*, cf_*); eine ansonsten gültige Anfrage deswegen scheitern zu lassen, wäre kontraproduktiv.

Standardwerte

Die Standardwerte sind für eine sichere interaktive Nutzung gewählt. Beispielsweise ist die Nutzung standardmäßig auf die letzten 30 Tage und Übersetzungen auf die 25 aktuellsten, nicht archivierten Datensätze eingestellt. Ein angefordertes Listenlimit über 100 wird auf 100 begrenzt.

Daten und Zeitstempel folgen dem ISO 8601-Standard. JSON-Feldnamen werden in snake_case geschrieben. Felder, die noch nicht anwendbar sind, sind in der Regel null, damit die Ressourcenstruktur über den Lebenszyklus einer Übersetzung stabil bleibt.

Cursor-Paginierung

Übergeben Sie den next_cursor aus einer Antwort unverändert an die nächste Anfrage. Stoppen Sie, wenn dieser null ist oder has_more den Wert false hat.

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 modifizieren Sie Cursor nicht selbst. Die Cursor-Paginierung verhindert, dass eine neu erstellte Übersetzung Zeilen zwischen den Seiten verschiebt.

Rate-Limits

Jede Anmeldedatei hat ein dauerhaftes Limit von 240 Anfragen pro Minute und eine Burst-Obergrenze von 40 Anfragen pro 10 Sekunden. Eine 429-Antwort enthält einen Retry-After-Header; warten Sie diesen ab, bevor Sie es erneut versuchen.

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

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

Dies gibt lediglich die Richtlinie an. Es wird keine Anzahl verbleibender Anfragen veröffentlicht. Richten Sie Ihre Anfragen daher an den dokumentierten Limits aus und behandeln Sie 429 zusammen mit Retry-After als Signal zum Reduzieren der Anfragenfrequenz.

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 an.

Wiederholen Sie Anfragen bei den Fehlern 429, 500, 502, 503 und 504 mit exponential backoff und Jitter. Wiederholen Sie keine Anfragen bei Validierungs-, Authentifizierungs-, Berechtigungs- oder „Not Found“-Fehlern, ohne die Anfrage zu ändern.

Trailing Slashes werden toleriert. Die REST-API sendet absichtlich keine Browser-CORS-Berechtigungen, da Workspace-Anmeldedaten in vertrauenswürdigem serverseitigem Code liegen sollten.