API-Keys, Rate Limits und der Aufbau einer echten Pipeline

Die REST API ist dieselbe, die die Web-UI verwendet. Der Unterschied besteht darin, dass ein Skript höflich sein kann, und die Plattform behandelt es entsprechend.

Keys

• Erstellen und Widerrufen von Keys unter Einstellungen → API-Keys.
• Beschränke jeden Key auf die jeweilige Aufgabe: Uploads, Lesezugriff oder voller Zugriff.
• Rotiere ohne Ausfallzeit, indem du während eines Deploys zwei Keys parallel nutzt.

curl -H "Authorization: Bearer $KEY" \
  -F "[email protected]" \
  https://zerostorage.net/api/files/upload

Rate Limits

Die Limits gelten pro Key und pro IP, wobei die verbleibende Budgetmenge in den Response-Headern angezeigt wird. Bei 429-Statuscodes auf diese Header zurückgreifen, anstatt eine feste Wartezeit einzulegen – das Budget füllt sich kontinuierlich auf.

Retry-Muster

1. 429- und 5xx-Fehler mit exponentiellem Backoff und Jitter wiederholen.
2. 401- oder 403-Fehler niemals wiederholen – stattdessen den Key rotieren.
3. Idempotenz entsteht durch Hashes: Das erneute Senden derselben Datei ist kostenlos.

Eine Pipeline, die dem Kontakt mit der Realität standhält

Bulk-Imports scheitern auf vorhersehbare Weise: Netzwerkprobleme, ein Key-Rotation während des Laufs und eine naive Schleife, die einen Server bombardiert, der sich noch erholt. Das Muster, das funktioniert, ist langweilig – die Arbeit in eine Warteschlange legen, eine Handvoll Worker ausführen und die Response-Header als Taktgeber nutzen. Den Hash jedes abgeschlossenen Elements persistieren, damit ein Neustart fortsetzt, anstatt zu wiederholen. Wenn ein Lauf mit Fehlern endet, ist das nützliche Artefakt eine Liste von Hashes und Statuscodes, keine Log-Datei, die man wie einen Roman lesen muss.

• Parallelität zuerst begrenzen; nur erhöhen, solange die Header noch Budget anzeigen.
• Fortschritt bei jedem Batch checkpointen, nicht bei jeder Datei.
• Bei dem Verhältnis von 429-Fehlern zu Erfolgen alarmieren – dieses Verhältnis ist das eigentliche Gesundheitssignal.

Nichts davon ist exotisch. Es ist der Unterschied zwischen einem Skript, das einmal auf deinem Laptop läuft, und einer Pipeline, die jemand anderes betreiben kann, ohne dich zu fragen, wie sie funktioniert. Schreibe das Runbook, solange die Fehlermodi noch frisch im Gedächtnis sind – welche Key-Scopes existieren, was die stabile Parallelität ist und wie ein gesunder Tag an Responses aussieht – denn die Person, die um 3 Uhr nachts aufgeweckt wird, wird nicht zuerst den Quellcode lesen.

API-Referenz durchsuchen und den Playground, bevor du irgendetwas in Produktion einbindest.