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

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

Roboflow の開発者向けツールは、少数のエラーカテゴリを共有しており、各ツールで異なる形で表示されます。このページは横断的なリファレンスです。

## CLI終了コード

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

| 終了コード | 意味                                                                   |
| ----- | -------------------------------------------------------------------- |
| `0`   | 成功                                                                   |
| `1`   | 一般エラー（不正な入力、ネットワーク障害、予期しないサーバー応答）                                    |
| `2`   | 認証失敗（API キーがない、または無効、ワークスペースが選択されていない）                               |
| `3`   | リソースが見つからない（project、version、workflow、deployment などが存在しないか、キーからは見えない） |

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

```bash
roboflow --json project get nonexistent 2>error.json
echo $?       # 3
cat error.json
# {"error": {"message": "Project 'nonexistent' not found", "hint": "Run 'roboflow project list' to see your projects."}}
```

## SDK の例外

Python SDK は失敗時に Python の例外を送出します。最もよく遭遇する型は次のとおりです:

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

経験則としては、 `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` | 見つかりません。ワークスペース、project、version、workflow、その他のリソースが存在しないか、キーからは見えません。                                                                                                   |
| `409` | 競合です。リソースが要求された操作を妨げる状態にあります（たとえば、親 project も Trash にある version を復元しようとした場合など）。                                                                                        |
| `423` | ロックされています。ワークスペースの請求が一時停止されています - 理由はレスポンス本文を参照してください。                                                                                                                 |
| `429` | レート制限されました。レスポンスに `Retry-After` ヘッダーがある場合は、再試行する前に少なくともその秒数だけ待ってください。そうでなければ、指数バックオフで再試行してください。                                                                        |
| `5xx` | サーバーエラー。バックオフ付きで安全に再試行できます。                                                                                                                                            |

### 標準エラーボディ

エラーは、少なくともトップレベルの `error` フィールドを含む JSON を返します:

```json
{
  "error": "Project 'nonexistent' not found"
}
```

一部のエンドポイントには `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": "Too many training read requests. Please retry later."
  }
}
```

API キーがない、または無効な状態での繰り返しリクエストは、IP アドレス単位で別途制限されます。これらは `429` を返し、プレーンテキスト本文で `Retry-After` ヘッダーなしで返されます。

### 必要なスコープ

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 レスポンスによるものは、バックオフ付きで再試行する候補です。