> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # Migration zu v4 > Was sich in @squarecloud/blob 4.0.0 geändert hat: eine sicherere Wiederholungsrichtlinie, weniger Standard-Wiederholungen, ein optionales SavedRule.active_from und ein konsistentes Batch-Löschen mit einer ID. Version 4.0.0 ändert, **wie das SDK Wiederholungen durchführt**, sodass es nur wiederholt, was sich gefahrlos wiederholen lässt. **Keine Methode, Option oder kein Export wurde umbenannt oder entfernt.** ## Voraussetzungen Unverändert: **Node.js 20** oder neuer, oder ein Browser; ESM und CommonJS. ## Zusammenfassung der Breaking Changes | v3.x | v4.x | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `429` wird wiederholt | **Wird nie wiederholt** (außer `TOO_MANY_CONCURRENT_CHUNKS` bei einem Multipart-Teil) | | Schreibvorgänge werden bei Netzwerkfehlern und `5xx` wiederholt | Schreibvorgänge erhalten **einen einzigen Versuch** | | Wiederholung nur bei `500` und `503` | Wiederholung bei **jedem `5xx`** (Lesevorgänge und Multipart-Teile) | | `maxRetries` Standard `5` | Standard **`2`** | | Backoff begrenzt auf 30 s | Begrenzt auf **8 s**: `min(8 s, 500 ms · 2^n) · U(0.5, 1)` | | `SavedRule.active_from: string` | `active_from?: string` (**optional**) | | `delete([id])` mit einer ID wirft `PREFIX_NOT_ALLOWED` | Meldet es in `failed` | | `RATE_LIMIT` in `BlobErrorCode` | **Veraltet** (weiterhin im Typ) | ## `429` wird nicht mehr wiederholt `RATE_LIMITED` umfasst sowohl ein Zeitfenster pro Route als auch eine Konto- oder IP-Sperre, die etwa 30 Minuten dauern kann, daher wiederholt das SDK ihn nicht mehr. Das schließt das Limit für einfache Uploads und `TOO_MANY_CONCURRENT_UPLOADS` ein. Behandle ihn selbst und warte, bevor du es erneut versuchst: ```typescript theme={"system"} import { SquareCloudBlobError } from "@squarecloud/blob"; try { await blob.put(file, { name: "report" }); } catch (error) { if (error instanceof SquareCloudBlobError && error.code === "RATE_LIMITED") { // back off: queue the job for later instead of retrying right away } throw error; } ``` Die einzige Ausnahme ist `TOO_MANY_CONCURRENT_CHUNKS` bei einem Multipart-Teil: Der Server lehnt den Teil ab, bevor er ihn liest, daher sendet das SDK ihn innerhalb von `maxRetries` erneut. ## Schreibvorgänge erhalten einen einzigen Versuch Netzwerkfehler und `5xx` werden jetzt nur noch bei `GET`-Aufrufen und bei Teilen von Multipart-Uploads wiederholt. Diese Aufrufe erhalten **einen Versuch**: * einfaches `put()` sowie Starten, Abschließen und Abbrechen eines Multipart-Uploads; * `update()`, `copy()`, `move()`, `delete()`; * `rules.set()`, `uploadTokens.create()`, `shares.create()`, `shares.revoke()`. Wiederhole einen Schreibvorgang nur dann selbst, wenn das für dich gefahrlos ist, zum Beispiel ein `put()` auf denselben Namen mit `overwrite: true`. Siehe [Schreibvorgänge selbst wiederholen](/de/sdks/blob/errors#schreibvorgänge-selbst-wiederholen). ## Weniger Wiederholungen, kürzeres Backoff `maxRetries` ist jetzt standardmäßig `2` (vorher `5`), und das Backoff ist auf 8 Sekunden begrenzt (vorher 30). Um das alte Budget für Lesevorgänge und Multipart-Teile beizubehalten: ```typescript theme={"system"} const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY, { maxRetries: 5 }); ``` Das bringt keine Wiederholungen bei `429` oder bei Schreibvorgängen zurück. ## `SavedRule.active_from` ist optional Die API sendet `active_from` nur bei Regeln mit `delete_after_days`. Berücksichtige in TypeScript `undefined`: ```typescript theme={"system"} const rules = await blob.rules.get(); for (const rule of rules) { if (rule.active_from) { console.log(`${rule.prefix} starts deleting at ${rule.active_from}`); } } ``` ## `delete([id])` mit einer einzelnen ID Ein Batch mit einer ID meldet `PREFIX_NOT_ALLOWED` jetzt wie jeder andere Batch in `failed`, statt zu werfen: ```typescript theme={"system"} // v3: threw SquareCloudBlobError (PREFIX_NOT_ALLOWED) // v4: const { failed } = await blob.delete([id]); // failed: [{ id, code: "PREFIX_NOT_ALLOWED" }] ``` `delete(id)` mit einem einfachen String wirft weiterhin. ## `RATE_LIMIT` ist veraltet Der Dienst sendet `RATE_LIMIT` nicht mehr: Die Konto- oder IP-Sperre ist `RATE_LIMITED`. Der alte Code bleibt in `BlobErrorCode`, damit bestehende Vergleiche weiterhin kompilieren; stelle sie auf `RATE_LIMITED` um. `DUPLICATE_RULE_PREFIX` wurde hinzugefügt. ## Korrekturen * Ein mitten im Lesen abgeschnittener Antwort-Body ist jetzt ein **Netzwerkfehler**: Er wird bei `GET`-Aufrufen und Multipart-Teilen wiederholt, ansonsten wird der ursprüngliche `fetch`-Fehler geworfen (früher war es `UNKNOWN_ERROR`). * Ein fehlgeschlagener Multipart-Upload **wartet jetzt auf die noch laufenden Teile**, bevor er abbricht, sodass kein Teil nach dem Abbruch ankommt und keine Anfrage `put()` überdauert. ## Checkliste Fange `RATE_LIMITED` ab und warte; das SDK wiederholt ihn nicht mehr. Füge eigene Wiederholungen nur bei Schreibvorgängen hinzu, die sich gefahrlos wiederholen lassen. Übergib `{ maxRetries: 5 }`, wenn du dich auf die alte Anzahl von Versuchen bei Lesevorgängen und Multipart-Teilen verlassen hast. Berücksichtige, dass `active_from` `undefined` sein kann, und ersetze `RATE_LIMIT` durch `RATE_LIMITED`.