> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/reference/ja/errors-and-status-codes.md).

# エラーとステータスコード

CLI の終了コード、SDK 例外、REST API エラーレスポンスのリファレンス。

Roboflow の開発者向けツール群は、少数のエラー分類を共有しており、各ツールでの表示方法は異なります。このページはそれらを横断的に参照するためのものです。

## CLI の終了コード

CLI は、スクリプトや AI エージェントが出力を解析せずに結果に応じて分岐できるよう、4 つの明確に定義された終了コードを使用します:

| 終了コード | 意味                                                               |
| ----- | ---------------------------------------------------------------- |
| `0`   | 成功                                                               |
| `1`   | 一般エラー（不正な入力、ネットワーク障害、予期しないサーバー応答）                                |
| `2`   | 認証失敗（API キーがない、無効な API キー、ワークスペース未選択）                            |
| `3`   | リソースが見つかりません（プロジェクト、バージョン、ワークフロー、デプロイメントなどが存在しない、またはそのキーからは見えない） |

では `--json` モードでは、CLI は成功時に stdout に構造化された出力を書き込み、失敗時には stderr に JSON エラーオブジェクトを書き込みます。そのため stdout は空のままになり、パイプラインを安全に解析できます:

```bash
roboflow --json project get nonexistent 2>error.json
echo $?       # 3
cat error.json
# {"error": {"message": "プロジェクト 'nonexistent' が見つかりません", "hint": "自分のプロジェクトを確認するには 'roboflow project list' を実行してください。"}}
```

## SDK の例外

Python SDK は失敗時に Python 例外を発生させます。よく遭遇する型は次のとおりです:

| 例外                                                   | 条件                                                                                        |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `RuntimeError`                                       | 操作が論理的に無効です。たとえば、 `restore()` Trash に入っていないプロジェクトに対して呼び出す場合や、まだ生成されていないバージョンで学習を行う場合などです。 |
| `ValueError`                                         | 渡された引数の形式が不正です。たとえば、認識されない `model_format` に対する `Version.download()`.                      |
| `roboflow.adapters.rfapi.RoboflowError`              | REST API が 2xx 以外のレスポンスを返しました。例外文字列にはサーバーのエラー本文が含まれます。                                    |
| `roboflow.adapters.deploymentapi.DeploymentApiError` | と同等 `RoboflowError` を専用デプロイメントサービス向けにしたものです。                                              |
| `requests.exceptions.HTTPError` / `ConnectionError`  | ネットワークレベルの障害（DNS、TLS、タイムアウト）。                                                             |

目安: 次を catch する `RuntimeError` 論理的な問題には `RoboflowError` サーバー側の拒否にはそれを使用し、それ以外はすべて上位に伝播させます。

```python
from roboflow.adapters import rfapi

try:
    project.restore()
except RuntimeError as e:
    print(f"Can't restore: {e}")
except rfapi.RoboflowError as e:
    print(f"Server rejected the request: {e}")
```

参照 [ロギングとデバッグ](/reference/ja/purattofmu/python-sdk/logging-and-debugging.md) 例外だけでは不十分な場合に、基礎となる HTTP リクエストを確認する方法について。

## REST API のステータスコード

REST API は標準の HTTP ステータスコードを使用します。Roboflow 特有の動作は次のとおりです:

| ステータス | 意味                                                                                                                                                                      |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | 成功。レスポンス本文は JSON です。                                                                                                                                                    |
| `204` | 成功、本文なし（いくつかの `PATCH` / `DELETE` エンドポイントで使用）。                                                                                                                           |
| `400` | リクエストの形式が不正です。必須フィールドの欠落、形状不正、無効な値。                                                                                                                                     |
| `401` | 認証失敗。 `api_key`がない、無効である、または操作に必要なスコープが欠けているキーです。                                                                                                                       |
| `402` | 支払いが必要です。ワークスペースのプランが要求された操作をサポートしていません。推論の場合、これはモデルまたはアーキテクチャがクレジットベースのプランでのみ利用可能であるか、ワークスペースの月間 Hosted API 推論クォータに達したことを意味します。レスポンス本文には `AccessException` エラー型が含まれます。 |
| `403` | 禁止されています。キーは認証されましたが、対象のワークスペースまたはリソースへのアクセス権がありません。                                                                                                                    |
| `404` | 見つかりません。ワークスペース、プロジェクト、バージョン、ワークフロー、またはその他のリソースが存在しない（またはそのキーからは見えません）。                                                                                                 |
| `409` | 競合です。リソースが要求された操作を妨げる状態にあります（たとえば、親プロジェクトも Trash にあるバージョンを復元しようとする場合）。                                                                                                  |
| `423` | ロックされています。ワークスペースの課金が一時停止中です。理由はレスポンス本文を参照してください。                                                                                                                       |
| `429` | レート制限です。少なくとも `Retry-After` 秒待ってから再試行してください。 `RateLimit-Limit`, `RateLimit-Remaining`、および `RateLimit-Reset` （秒）は、到達したバケットを示します。                                         |
| `5xx` | サーバーエラーです。バックオフして再試行しても安全です。                                                                                                                                            |

### 標準エラー本文

エラーは、少なくとも最上位の `error` フィールドを含む JSON を返します:

```json
{
  "error": "プロジェクト 'nonexistent' が見つかりません"
}
```

一部のエンドポイントには、 `hint` または構造化されたエラーオブジェクトも含まれます。詳細は、以下の各エンドポイントのドキュメントを参照してください: [REST API](/reference/ja/purattofmu/rest-api.md) 詳細について。

### 学習読み取りのレート制限

学習読み取りエンドポイント（`GET /:workspace/:project/:version/v2/trainings`, `.../v2/trainings/get`、および `.../v2/trainings/recipe`）は、API キーごとおよびワークスペースごとにリクエスト数をカウントします。同じ IP アドレスからの他のトラフィックはカウント対象外です。スロットリングされたリクエストは `429` 、 `Retry-After` ヘッダー付きで、次の本文を返します:

```json
{
  "error": {
    "code": "training_read_rate_limit_exceeded",
    "message": "学習読み取りリクエストが多すぎます。後でもう一度お試しください。"
  }
}
```

API キーがない、または無効な場合の繰り返しリクエストは、IP アドレスごとに別途制限されます。それらは `429` プレーンテキスト本文と同じ `Retry-After` および `RateLimit-*` ヘッダーを返します。

### 必要なスコープ

API キーにはリソースごとのスコープが付与されています。書き込み操作で 401 が返る場合、多くはキーに対応する `*:update` または `*:write` スコープがないことを意味します。リソースの読み取りはできても同様です。 [スコープ付き API キー](/reference/ja/ren-zheng/authentication/scoped-api-keys.md) でスコープの参照を確認してください。

## ツール横断のエラー対応表

| 状況                | CLI の終了 | SDK                                      | REST  |
| ----------------- | ------- | ---------------------------------------- | ----- |
| API キーがない／無効      | `2`     | `RoboflowError` ("401")                  | `401` |
| リソースが見つかりません      | `3`     | `RoboflowError` ("404") / `RuntimeError` | `404` |
| プラン制限／クォータ超過      | `1`     | `RoboflowError` ("402")                  | `402` |
| 不正な入力／不正な形式のリクエスト | `1`     | `ValueError` / `RoboflowError` ("400")   | `400` |
| サーバーエラー／一時的な障害    | `1`     | `RoboflowError` （「5xx」）                  | `5xx` |

再試行処理を組み込む際はこの表を使ってください:   `2` / 401 は自動再試行すべきではありません（キーが有効になることはないためです）、 `3` / 404 も再試行すべきではありませんが、 `1` 5xx レスポンスからのものはバックオフ付き再試行の候補です。