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

# Migrando para a v4

> O que mudou no @squarecloud/blob 4.0.0: uma política de novas tentativas mais segura, menos novas tentativas por padrão, um SavedRule.active_from opcional e uma exclusão em lote consistente com um único id.

A versão 4.0.0 muda **a forma como o SDK faz novas tentativas**, para que ele só repita o que é seguro repetir. **Nenhum método, opção ou export foi renomeado ou removido.**

## Requisitos

Inalterados: **Node.js 20** ou superior, ou um navegador; ESM e CommonJS.

## Resumo das breaking changes

| v3.x                                                | v4.x                                                                               |
| --------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `429` repetido                                      | **Nunca repetido** (exceto `TOO_MANY_CONCURRENT_CHUNKS` em uma parte de multipart) |
| Escritas repetidas em erros de rede e `5xx`         | Escritas têm **uma única tentativa**                                               |
| Repetido apenas em `500` e `503`                    | Repetido em **qualquer `5xx`** (leituras e partes de multipart)                    |
| `maxRetries` padrão `5`                             | Padrão **`2`**                                                                     |
| Backoff limitado a 30 s                             | Limitado a **8 s**: `min(8 s, 500 ms · 2^n) · U(0.5, 1)`                           |
| `SavedRule.active_from: string`                     | `active_from?: string` (**opcional**)                                              |
| `delete([id])` com um id lança `PREFIX_NOT_ALLOWED` | Informa-o em `failed`                                                              |
| `RATE_LIMIT` em `BlobErrorCode`                     | **Depreciado** (ainda no tipo)                                                     |

## `429` não é mais repetido

`RATE_LIMITED` cobre tanto uma janela por rota quanto um bloqueio de conta ou IP que pode durar cerca de 30 minutos, então o SDK não o repete mais. Isso inclui o limite de upload simples e `TOO_MANY_CONCURRENT_UPLOADS`. Trate-o você mesmo e aguarde antes de tentar novamente:

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

A única exceção é `TOO_MANY_CONCURRENT_CHUNKS` em uma parte de multipart: o servidor recusa a parte antes de lê-la, então o SDK a envia novamente dentro de `maxRetries`.

## Escritas têm uma única tentativa

Erros de rede e `5xx` agora só são repetidos em chamadas `GET` e em partes de uploads multipart. Estas chamadas têm **uma tentativa**:

* `put()` simples, e início, conclusão e cancelamento de um upload multipart;
* `update()`, `copy()`, `move()`, `delete()`;
* `rules.set()`, `uploadTokens.create()`, `shares.create()`, `shares.revoke()`.

Repita uma escrita por conta própria apenas quando for seguro para você, por exemplo um `put()` com o mesmo nome e `overwrite: true`. Veja [Repetindo escritas por conta própria](/pt-br/sdks/blob/errors#repetindo-escritas-por-conta-própria).

## Menos novas tentativas, backoff mais curto

`maxRetries` agora tem padrão `2` (era `5`), e o backoff é limitado a 8 segundos (era 30). Para manter o limite antigo em leituras e partes de multipart:

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

Isso não traz de volta as novas tentativas em `429` nem em escritas.

## `SavedRule.active_from` é opcional

A API só envia `active_from` para regras com `delete_after_days`. Em TypeScript, trate o caso `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])` com um único id

Um lote com um id agora informa `PREFIX_NOT_ALLOWED` em `failed`, como qualquer outro lote, em vez de lançar erro:

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

`delete(id)` com uma string simples continua lançando erro.

## `RATE_LIMIT` está depreciado

O serviço não envia mais `RATE_LIMIT`: o bloqueio de conta ou IP é `RATE_LIMITED`. O código antigo permanece em `BlobErrorCode` para que as comparações existentes continuem compilando; troque-as por `RATE_LIMITED`. `DUPLICATE_RULE_PREFIX` foi adicionado.

## Correções

* Um corpo de resposta cortado no meio da leitura agora é um **erro de rede**: ele é repetido em chamadas `GET` e partes de multipart e, caso contrário, o erro original do `fetch` é lançado (antes era `UNKNOWN_ERROR`).
* Um upload multipart que falha agora **aguarda as partes ainda em andamento** antes de cancelar, para que nenhuma parte chegue depois do cancelamento e nenhuma requisição sobreviva ao `put()`.

## Checklist

<Steps>
  <Step title="Trate o 429 você mesmo">
    Capture `RATE_LIMITED` e aguarde; o SDK não o repete mais.
  </Step>

  <Step title="Revise as escritas">
    Adicione sua própria nova tentativa apenas às escritas que são seguras de repetir.
  </Step>

  <Step title="Escolha um limite de novas tentativas">
    Passe `{ maxRetries: 5 }` se você dependia do número antigo de tentativas em leituras e partes de multipart.
  </Step>

  <Step title="Atualize os tipos">
    Trate o caso de `active_from` ser `undefined` e substitua `RATE_LIMIT` por `RATE_LIMITED`.
  </Step>
</Steps>