> ## 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. # エラーとリトライ > SquareCloudBlobError、BlobErrorCode の一覧、ラップされないネットワークエラー、そして @squarecloud/blob がどの呼び出しをリトライするかを正確に説明します。 ## `SquareCloudBlobError` API のあらゆる失敗は `SquareCloudBlobError` をスローします。 | プロパティ | 型 | 説明 | | --------------------- | ------------------------- | ---------------------------------------------------------------------------------------------- | | `status` | `number` | レスポンスの HTTP ステータス。 | | `code` | `BlobErrorCode` | API のエラーコード (例: `OBJECT_NOT_FOUND`)。 | | `message` | `string` | サーバーによる説明。説明がない場合はコード。 | | `extra` | `Record` | エラーボディのその他すべてのフィールド (例: ルールのエラーでの `prefix`)。 | | `isUpgradeRequired()` | `() => boolean` | `UPGRADE_REQUIRED` の場合に `true`。これはプランによるあらゆる拒否 (上限、機能、プラン) のコードです。どれに該当するかは `message` に記載されます。 | ```typescript theme={"system"} import { SquareCloudBlob, SquareCloudBlobError } from "@squarecloud/blob"; const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY); try { await blob.shares.create(id, { password: "secret123" }); } catch (error) { if (error instanceof SquareCloudBlobError) { if (error.isUpgradeRequired()) { console.error(error.message); // your plan lacks this feature or limit } else if (error.code === "OBJECT_NOT_FOUND") { // ... } else { console.error(error.status, error.code, error.extra); } } else { throw error; // network error or file error, see below } } ``` ### `SquareCloudBlobError` にならないもの * **ネットワークエラーはラップされません。** リクエストが完全なレスポンスを得られなかった場合 (DNS の失敗、接続のリセット、読み取り途中でのボディの途切れ)、[リトライ](#リトライポリシー)の後、元の `fetch` のエラーがそのままスローされます。 * **ファイルのエラー。** Node.js では、開けない `put()` のパスはプレーンな `Error` (`Cannot open file: `、元のエラーは `cause`) をスローします。ブラウザでは、パスは `node:fs` のインポートエラーで失敗します。 * **`@aws-sdk/client-s3` がない場合。** [`s3()`](/ja/sdks/blob/s3) はモジュールのインポートエラーをスローします。 ### `UNKNOWN_ERROR` `UNKNOWN_ERROR` は **SDK 自身が生成する唯一のコード**です。レスポンスにエラーコードがない場合、つまり JSON ではないボディ (プロキシのエラーページなど) や、`status: "success"` を含まない `2xx` レスポンスの場合に使われます。`status` には実際の HTTP ステータスが入ります。 ### オブジェクトごとの失敗 バッチ操作は、例外をスローする代わりに結果の中で失敗を報告します: * [`update()`](/ja/sdks/blob/objects#オブジェクトの更新): 各結果に `ok: false` と `code` が含まれます。 * [`delete([ids])`](/ja/sdks/blob/objects#削除): 存在しないオブジェクトは `not_found` に、その他の失敗は `failed` に入ります。 ## エラーコード `BlobErrorCode` は Blob Storage API 独自のコード一覧です。メインの Square Cloud API のエラーコードとは**別の**一覧です。各コードの HTTP ステータスと意味については、[Blob API エラーリファレンス](/ja/blob-reference/errors)を参照してください。 `ACCESS_DENIED`, `RATE_LIMITED`, `MISSING_SCOPE`, `RESOURCE_NOT_ALLOWED`, `UPLOAD_TOKEN_NOT_ALLOWED`, `UPLOAD_TOKEN_USED`, `PREFIX_NOT_ALLOWED`, `PERMISSION_DENIED`, `ACCOUNT_BLOCKED`, `UPGRADE_REQUIRED`, `STORAGE_QUOTA_EXCEEDED`, `PRIVATE_STORAGE_UNAVAILABLE`, `PUBLIC_STORAGE_UNAVAILABLE`, `TOO_MANY_CONCURRENT_UPLOADS`, `UPLOAD_FAILED`, `INTERNAL_SERVER_ERROR`, `NOT_FOUND` `RATE_LIMIT` は**非推奨**です。サービスはもう送信しませんが (`RATE_LIMITED` を参照)、型には残っています。 `OBJECT_NOT_FOUND`, `OBJECT_ALREADY_EXISTS`, `OBJECT_IS_LEGACY`, `CHECKSUM_MISMATCH`, `INVALID_CONTENT_TYPE`, `FILE_TOO_LARGE`, `FILE_TOO_SMALL`, `BLOCKED_FILE_TYPE`, `INVALID_FILE_TYPE`, `FILE_TYPE_NOT_ALLOWED`, `NOTHING_TO_UPDATE`, `VISIBILITY_CHANGE_FAILED`, `UPDATE_FAILED`, `DELETE_FAILED`, `TOO_MANY_OBJECTS`, `SAME_OBJECT`, `INVALID_DESTINATION`, `COPY_FAILED`, `PREFIX_REQUIRED`, `INVALID_CONTINUATION_TOKEN` `TOO_MANY_CONCURRENT_CHUNKS`, `TOO_MANY_OPEN_UPLOADS`, `INVALID_UPLOAD_TOKEN`, `UPLOAD_NOT_FOUND`, `NO_CHUNKS_UPLOADED`, `EMPTY_CHUNK`, `INVALID_CHUNK_PART`, `CHUNK_TOO_SMALL`, `CHUNK_TOO_LARGE` `TOO_MANY_RULES`, `DUPLICATE_RULE_PREFIX`, `INVALID_RULES`, `UPLOAD_TOKEN_TOO_LARGE`, `TOO_MANY_SHARES`, `SHARE_NOT_FOUND`, `INVALID_SHARE`, `API_KEY_REQUIRED`, `LEGACY_API_KEY` `INVALID_OBJECT`、`INVALID_OBJECT_NAME`、`INVALID_RULE_PREFIX` などの任意の `INVALID_*` コード。ルールのエラーでは、問題のある `prefix` が `error.extra` に含まれます。 `UNKNOWN_ERROR`: レスポンスにエラーコードがなかった ([上記](#unknown_error)を参照)。 `BlobErrorCode` は他の任意の文字列も受け付けるため、サービスが後から追加したコードも型チェックを通ります。 ## リトライポリシー SDK は**安全に繰り返せる**ものだけをリトライします: `GET` の呼び出しと、マルチパートアップロードの**パート** (各パート番号は再送できます) です。 | リトライ | 呼び出し | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **あり**、最大 `maxRetries` 回 (デフォルト 2) | `list()`、`listPage()`、`info()`、`downloadUrl()`、`stats()`、`rules.get()`、`shares.list()`、`s3Credentials()`、およびマルチパート `put()` の各パート | | **なし**、1 回のみ試行 | シンプルな `put()`、マルチパートアップロードの開始・完了・中止、`update()`、`copy()`、`move()`、`delete()`、`rules.set()`、`uploadTokens.create()`、`shares.create()`、`shares.revoke()` | リトライ可能な呼び出しは、次の場合にリトライされます: * **ネットワークエラー** (読み取り途中でのボディの途切れを含む) * **すべての `5xx`** レスポンス * マルチパートのパートでの `TOO_MANY_CONCURRENT_CHUNKS`: サーバーはパートを読み取る前に拒否するため、同じリトライ回数の範囲内で再送されます その他の `4xx` では、**`429` も含めて**決してリトライされません。`RATE_LIMITED` は約 30 分続くアカウントのブロックである可能性があるため、SDK はその判断をあなたに委ねます。 ### バックオフ リトライ `n` 回目 (0 から開始) の前に、SDK は次の時間だけ待機します: ```text theme={"system"} min(8 s, 500 ms · 2^n) · U(0.5, 1) ``` つまり、上限 8 秒の指数バックオフに、遅延の 50 %〜100 % のジッターを加えたものです。デフォルトの `maxRetries: 2` では、1 回の呼び出しは最大 3 回試行されます。 ### 書き込みを自分でリトライする ネットワークエラーや `5xx` で失敗した書き込みは、適用されている場合もされていない場合もあります。繰り返しても安全な場合にのみリトライしてください。たとえば、同じ `name` に `overwrite: true` で行う `put()` です。 ```typescript theme={"system"} import { SquareCloudBlobError } from "@squarecloud/blob"; async function putWithRetry(file, options, attempts = 3) { for (let i = 0; ; i++) { try { return await blob.put(file, { ...options, overwrite: true }); } catch (error) { // fetch network errors are TypeErrors; 5xx are SquareCloudBlobErrors const retryable = error instanceof SquareCloudBlobError ? error.status >= 500 : error instanceof TypeError; if (!retryable || i + 1 >= attempts) throw error; await new Promise((r) => setTimeout(r, 1000 * 2 ** i)); } } } ``` `429 RATE_LIMITED` を短い間隔のループでリトライしないでください。アカウント全体の制限を超えると、アカウントが約 30 分間ブロックされることがあります。[Blob API エラーリファレンス](/ja/blob-reference/errors)を参照してください。 ### タイムアウト クライアントのタイムアウトはなく、呼び出しをキャンセルする方法もありません。リクエストは `fetch` が待機する限り続きます。