Skip to main content

SquareCloudBlobError

API のあらゆる失敗は SquareCloudBlobError をスローします。

SquareCloudBlobError にならないもの

  • ネットワークエラーはラップされません。 リクエストが完全なレスポンスを得られなかった場合 (DNS の失敗、接続のリセット、読み取り途中でのボディの途切れ)、リトライの後、元の fetch のエラーがそのままスローされます。
  • ファイルのエラー。 Node.js では、開けない put() のパスはプレーンな Error (Cannot open file: <path>、元のエラーは cause) をスローします。ブラウザでは、パスは node:fs のインポートエラーで失敗します。
  • @aws-sdk/client-s3 がない場合。 s3() はモジュールのインポートエラーをスローします。

UNKNOWN_ERROR

UNKNOWN_ERROR は SDK 自身が生成する唯一のコードです。レスポンスにエラーコードがない場合、つまり JSON ではないボディ (プロキシのエラーページなど) や、status: "success" を含まない 2xx レスポンスの場合に使われます。status には実際の HTTP ステータスが入ります。

オブジェクトごとの失敗

バッチ操作は、例外をスローする代わりに結果の中で失敗を報告します:
  • update(): 各結果に ok: false と code が含まれます。
  • delete([ids]): 存在しないオブジェクトは not_found に、その他の失敗は failed に入ります。

エラーコード

BlobErrorCode は Blob Storage API 独自のコード一覧です。メインの Square Cloud API のエラーコードとは別の一覧です。各コードの HTTP ステータスと意味については、Blob API エラーリファレンスを参照してください。
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_FOUNDRATE_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: レスポンスにエラーコードがなかった (上記を参照)。
BlobErrorCode は他の任意の文字列も受け付けるため、サービスが後から追加したコードも型チェックを通ります。

リトライポリシー

SDK は安全に繰り返せるものだけをリトライします: GET の呼び出しと、マルチパートアップロードのパート (各パート番号は再送できます) です。 リトライ可能な呼び出しは、次の場合にリトライされます:
  • ネットワークエラー (読み取り途中でのボディの途切れを含む)
  • すべての 5xx レスポンス
  • マルチパートのパートでの TOO_MANY_CONCURRENT_CHUNKS: サーバーはパートを読み取る前に拒否するため、同じリトライ回数の範囲内で再送されます
その他の 4xx では、429 も含めて決してリトライされません。RATE_LIMITED は約 30 分続くアカウントのブロックである可能性があるため、SDK はその判断をあなたに委ねます。

バックオフ

リトライ n 回目 (0 から開始) の前に、SDK は次の時間だけ待機します:
つまり、上限 8 秒の指数バックオフに、遅延の 50 %〜100 % のジッターを加えたものです。デフォルトの maxRetries: 2 では、1 回の呼び出しは最大 3 回試行されます。

書き込みを自分でリトライする

ネットワークエラーや 5xx で失敗した書き込みは、適用されている場合もされていない場合もあります。繰り返しても安全な場合にのみリトライしてください。たとえば、同じ name に overwrite: true で行う put() です。
429 RATE_LIMITED を短い間隔のループでリトライしないでください。アカウント全体の制限を超えると、アカウントが約 30 分間ブロックされることがあります。Blob API エラーリファレンスを参照してください。

タイムアウト

クライアントのタイムアウトはなく、呼び出しをキャンセルする方法もありません。リクエストは fetch が待機する限り続きます。