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

# JavaScript SDK: エラーとリトライ

> @squarecloud/api で SquareCloudAPIError を処理します: ステータス、コード、メッセージ、SDK 独自のエラーコード、リトライ、タイムアウト、レート制限。

API、ネットワーク、ローカルのあらゆる失敗は、1 つのクラス `SquareCloudAPIError` としてスローされます。

サンプルでは、[クライアントの作成](/ja/sdks/js/client#クライアントの作成)で作成した `api` クライアントを使います。`appId` はあなたのアプリの ID で、[`api.account.me()`](/ja/sdks/js/client#アカウント) で一覧できます。

```typescript theme={"system"}
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` | [タイムアウト](/ja/sdks/js/client#タイムアウト)内にレスポンスがなかった |
| 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 ステータスで処理してください**:

```typescript theme={"system"}
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 エラーリファレンス](/ja/api-reference/errors)には各コードの HTTP ステータス、意味、対処法が掲載されており、SDK の各ページにはそのメソッドがよく返すコードを掲載しています。どの呼び出しでも、401 `ACCESS_DENIED` (不正なキー)、403 `MISSING_SCOPE` または `RESOURCE_NOT_ALLOWED` ([キーの制限](/ja/sdks/js/client#api-キーとスコープ))、429 ([レート制限](#レート制限)を参照)、503 `DATABASE_UNAVAILABLE` が返ることがあります。

`ai.chat()` のエラーは、代わりに小文字の OpenAI コード (`access_denied`、`rate_limit_exceeded`、`server_overloaded` など) を使います。[AI](/ja/sdks/js/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 秒の下限がある呼び出しとタイムアウトのない呼び出しについては、[タイムアウト](/ja/sdks/js/client#タイムアウト)を参照してください。タイムアウトはステータス `0` の `TIMEOUT` をスローし、リトライされることはありません。

## レート制限

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

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

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

## 次のステップ

<CardGroup cols={2}>
  <Card title="API エラーリファレンス" icon="book" href="/ja/api-reference/errors">
    すべてのエラーコードと、その意味と対処法。
  </Card>

  <Card title="制限と制約" icon="gauge" href="/ja/api-reference/limitations-and-restrictions">
    各プランのリクエスト制限。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.