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

# Migrazione a v4

> Cosa è cambiato in @squarecloud/blob 4.0.0: una politica di retry più sicura, meno retry predefiniti, un SavedRule.active_from opzionale e un'eliminazione batch coerente con un solo id.

La versione 4.0.0 cambia **il modo in cui l'SDK ripete le richieste**, così che ripeta solo ciò che è sicuro ripetere. **Nessun metodo, opzione o export è stato rinominato o rimosso.**

## Requisiti

Invariati: **Node.js 20** o più recente, oppure un browser; ESM e CommonJS.

## Riepilogo delle modifiche incompatibili

| v3.x                                                      | v4.x                                                                          |
| --------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `429` ripetuto                                            | **Mai ripetuto** (tranne `TOO_MANY_CONCURRENT_CHUNKS` su una parte multipart) |
| Scritture ripetute in caso di errori di rete e `5xx`      | Le scritture hanno **un solo tentativo**                                      |
| Ripetuto solo su `500` e `503`                            | Ripetuto su **qualsiasi `5xx`** (letture e parti multipart)                   |
| `maxRetries` predefinito `5`                              | Predefinito **`2`**                                                           |
| Backoff limitato a 30 s                                   | Limitato a **8 s**: `min(8 s, 500 ms · 2^n) · U(0.5, 1)`                      |
| `SavedRule.active_from: string`                           | `active_from?: string` (**opzionale**)                                        |
| `delete([id])` con un solo id lancia `PREFIX_NOT_ALLOWED` | Lo riporta in `failed`                                                        |
| `RATE_LIMIT` in `BlobErrorCode`                           | **Deprecato** (ancora presente nel tipo)                                      |

## `429` non viene più ripetuto

`RATE_LIMITED` copre sia una finestra per route sia un blocco dell'account o dell'IP che può durare circa 30 minuti, quindi l'SDK non lo ripete più. Questo include il limite degli upload semplici e `TOO_MANY_CONCURRENT_UPLOADS`. Gestiscilo tu e attendi prima di riprovare:

```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;
}
```

L'unica eccezione è `TOO_MANY_CONCURRENT_CHUNKS` su una parte multipart: il server rifiuta la parte prima di leggerla, quindi l'SDK la invia di nuovo entro `maxRetries`.

## Le scritture hanno un solo tentativo

Gli errori di rete e i `5xx` ora vengono ripetuti solo sulle chiamate `GET` e sulle parti degli upload multipart. Queste chiamate hanno **un solo tentativo**:

* `put()` semplice, e avvio, completamento e annullamento di un upload multipart;
* `update()`, `copy()`, `move()`, `delete()`;
* `rules.set()`, `uploadTokens.create()`, `shares.create()`, `shares.revoke()`.

Ripeti tu una scrittura solo quando per te è sicuro farlo, ad esempio un `put()` sullo stesso nome con `overwrite: true`. Vedi [Ripetere tu le scritture](/it/sdks/blob/errors#ripetere-tu-le-scritture).

## Meno retry, backoff più breve

`maxRetries` ora ha come valore predefinito `2` (prima `5`), e il backoff è limitato a 8 secondi (prima 30). Per mantenere il vecchio budget su letture e parti multipart:

```typescript theme={"system"}
const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY, { maxRetries: 5 });
```

Questo non ripristina i retry su `429` o sulle scritture.

## `SavedRule.active_from` è opzionale

L'API invia `active_from` solo per le regole con `delete_after_days`. In TypeScript, gestisci `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])` con un solo id

Un batch con un solo id ora riporta `PREFIX_NOT_ALLOWED` in `failed`, come qualsiasi altro batch, invece di lanciare un errore:

```typescript theme={"system"}
// v3: threw SquareCloudBlobError (PREFIX_NOT_ALLOWED)
// v4:
const { failed } = await blob.delete([id]);
// failed: [{ id, code: "PREFIX_NOT_ALLOWED" }]
```

`delete(id)` con una semplice stringa lancia ancora un errore.

## `RATE_LIMIT` è deprecato

Il servizio non invia più `RATE_LIMIT`: il blocco dell'account o dell'IP è `RATE_LIMITED`. Il vecchio codice resta in `BlobErrorCode` così i confronti esistenti continuano a compilare; sostituiscili con `RATE_LIMITED`. È stato aggiunto `DUPLICATE_RULE_PREFIX`.

## Correzioni

* Un body della risposta troncato durante la lettura è ora un **errore di rete**: viene ripetuto sulle chiamate `GET` e sulle parti multipart, altrimenti viene lanciato l'errore originale di `fetch` (prima era `UNKNOWN_ERROR`).
* Un upload multipart fallito ora **attende le parti ancora in transito** prima di annullare, così nessuna parte arriva dopo l'annullamento e nessuna richiesta sopravvive a `put()`.

## Checklist

<Steps>
  <Step title="Gestisci tu il 429">
    Intercetta `RATE_LIMITED` e rallenta; l'SDK non lo ripete più.
  </Step>

  <Step title="Rivedi le scritture">
    Aggiungi un tuo retry solo alle scritture sicure da ripetere.
  </Step>

  <Step title="Scegli un budget di retry">
    Passa `{ maxRetries: 5 }` se facevi affidamento sul vecchio numero di tentativi per letture e parti multipart.
  </Step>

  <Step title="Aggiorna i tipi">
    Gestisci il caso in cui `active_from` sia `undefined`, e sostituisci `RATE_LIMIT` con `RATE_LIMITED`.
  </Step>
</Steps>