JavaScript SDK: エラーとリトライ

API、ネットワーク、ローカルのあらゆる失敗は、1 つのクラス SquareCloudAPIError としてスローされます。サンプルでは、クライアントの作成で作成した api クライアントを使います。appId はあなたのアプリの ID で、api.account.me() で一覧できます。

import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

try {
    await api.apps.start(appId);
} catch (error) {
    if (error instanceof SquareCloudAPIError) {
        console.error(error.status, error.code, error.message);
        console.error(error.method, error.path); // "POST" "/v2/apps/<id>/start"
    }
}

`SquareCloudAPIError`

SquareCloudAPIError は Error を継承しています (TypeError ではありません)。

プロパティ	型	説明
`status`	`number`	HTTP ステータス。レスポンスが届かなかった場合 (ネットワークエラー、タイムアウト、ローカルチェック) は `0`
`code`	`ErrorCode`	API のエラーコード (例: `APP_NOT_FOUND`)、または SDK 独自のコードのいずれか
`message`	`string`	サーバーによる説明。サーバーがコードしか送らなかった場合は、そのコード自体
`method`	`string`	失敗した呼び出しの HTTP メソッド
`path`	`string`	失敗した呼び出しの URL パス (クエリ文字列を除く)
`cause`	`unknown`	元のエラー。`NETWORK_ERROR` と不正な JSON の場合に設定されます

次の 2 つの失敗はラップされません:

中断された呼び出しは、シグナルの reason で reject されます。中断された realtime() のループは単に終了します。
開けないアップロードパスは、ファイルシステムのエラーをスローします。

SDK のコード

ステータス	コード	発生条件
0	`NETWORK_ERROR`	レスポンスがない (DNS、接続のリセット、ボディの途切れ)。元のエラーは `cause` に入ります
0	`TIMEOUT`	タイムアウト内にレスポンスがなかった
0	`FILE_TOO_LARGE`	ローカルチェック: 100 MB を超えるアップロード、または 10 MB を超える `files.write`。何も送信されていません
0	`INVALID_ID`	ローカルチェック: 空、`.`、`..` の ID。何も送信されていません
任意	`UNKNOWN_ERROR`	コードのないレスポンス (プロキシのエラーページなど)。実際の `status` と、メッセージ `HTTP <status>` を持ちます。JSON ではない 2xx のボディは、メッセージ `Invalid JSON in HTTP <status> response` になります

`ErrorCode` 型

ErrorCode は型のみです (ランタイムのオブジェクトはありません)。公開されているすべての API コード、非推奨のコード、SDK のコードに加えて string & {} を列挙しているため、エディターは既知のコードを補完し、新しいコードも型チェックを通ります。RATE_LIMIT と RATE_LIMIT_EXCEEDED は非推奨として型に残っていますが、API は現在どちらの場合も RATE_LIMITED を返します。 API コードの一覧は増えていきます。不明なコードは HTTP ステータスで処理してください:

async function start(appId: string) {
    try {
        await api.apps.start(appId);
    } catch (error) {
        if (!(error instanceof SquareCloudAPIError)) throw error;

        switch (error.code) {
            case "APP_NOT_FOUND":
                return null;
            case "CONTAINER_ALREADY_STARTED":
                return; // fine
            default:
                if (error.status === 429) return retryLater();
                if (error.status >= 500) return reportOutage(error);
                throw error;
        }
    }
}

API のエラーコード

その他のコードはすべて API から返されます。API エラーリファレンスには各コードの HTTP ステータス、意味、対処法が掲載されており、SDK の各ページにはそのメソッドがよく返すコードを掲載しています。どの呼び出しでも、401 ACCESS_DENIED (不正なキー)、403 MISSING_SCOPE または RESOURCE_NOT_ALLOWED (キーの制限)、429 (レート制限を参照)、503 DATABASE_UNAVAILABLE が返ることがあります。 ai.chat() のエラーは、代わりに小文字の OpenAI コード (access_denied、rate_limit_exceeded、server_overloaded など) を使います。AI を参照してください。

リトライ

SDK は安全に繰り返せるものだけを、最大 maxRetries 回 (デフォルトは 2 なので、最大 3 回の試行) リトライします:

リトライ対象	メソッド
`NETWORK_ERROR`	`GET` のみ
503 `UPLOAD_BUSY`	すべてのメソッド
503 `ANALYTICS_BUSY`	すべてのメソッド
503 `DATABASE_UNAVAILABLE`	`GET` のみ

次のものは決してリトライしません:

TIMEOUT
すべての 429: RATE_LIMITED は約 30 分のブロックである可能性があり、KEEP_CALM もリトライされません
その他の 5xx
AI のエラー

503 DATABASE_UNAVAILABLE は変更がすでに適用された後に返されることがあるため、SDK は GET 以外ではリトライしません。必要であれば、冪等な変更は自分でリトライしてください。リトライ n 回目 (0 から開始) の前の待機時間は min(8 s, 500 ms · 2^n) · U(0.5, 1) です。50%〜100% のジッターを伴う指数バックオフです。リトライを無効にするには maxRetries: 0 を設定します。

タイムアウト

timeoutMs (30 秒) は試行ごとに適用され、レスポンス全体が対象です。120 秒の下限がある呼び出しとタイムアウトのない呼び出しについては、タイムアウトを参照してください。タイムアウトはステータス 0 の TIMEOUT をスローし、リトライされることはありません。

レート制限

すべてのアカウントには、プランによって決まる 60 秒あたりのリクエスト数の制限があり (値)、一部のルートには独自の制限があります:

429 RATE_LIMITED: アカウントまたは API キーがリクエストの上限を超えると、約 30 分ブロックされます。無効なキーを送り続ける IP も短時間ブロックされます。ネットワーク系 endpoint と account.snapshots の制限でもあります。
429 KEEP_CALM: 短時間に 1 つのルートへの呼び出しが多すぎる。

SDK は 429 を決してリトライしません。ペースを落とし、しばらく待ってから再試行してください。

CLI

VS Code

SDKs

JavaScript SDK: エラーとリトライ

`SquareCloudAPIError`

SDK のコード

`ErrorCode` 型

API のエラーコード

リトライ

タイムアウト

レート制限

次のステップ

API エラーリファレンス

制限と制約

​SquareCloudAPIError

​SDK のコード

​ErrorCode 型

​API のエラーコード

​リトライ

​タイムアウト

​レート制限

​次のステップ

API エラーリファレンス

制限と制約

`SquareCloudAPIError`

SDK のコード

`ErrorCode` 型

API のエラーコード

リトライ

タイムアウト

レート制限

次のステップ