> 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は4つの明確に定義された終了コードを使用するため、スクリプトやAIエージェントは出力を解析せずに結果に応じて分岐できます:

| 終了コード | 意味                                                                     |
| ----- | ---------------------------------------------------------------------- |
| `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": "'roboflow project list' を実行してプロジェクトを確認してください。"}}
```

## SDKの例外

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

| 例外                                                   | 発生条件                                                                                         |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `RuntimeError`                                       | 操作が論理的に不正です - たとえば、 `restore()` Trash にないプロジェクトに対して呼び出す場合や、まだ生成されていない version でトレーニングする場合など。 |
| `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"復元できません: {e}")
except rfapi.RoboflowError as e:
    print(f"サーバーがリクエストを拒否しました: {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` | 競合。リソースが、要求された操作を妨げる状態にあります（たとえば、親プロジェクトもTrashにあるversionを復元しようとした場合など）。                                                                                              |
| `423` | ロックされています。ワークスペースの請求が一時停止されています - 理由はレスポンス本文を参照してください。                                                                                                               |
| `429` | レート制限されています。減速し、指数バックオフで再試行してください。                                                                                                                                   |
| `5xx` | サーバーエラー。バックオフ付きで安全に再試行できます。                                                                                                                                          |

### 標準のエラー本文

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

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

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

### 必須スコープ

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 は自動再試行してはいけません（キーがさらに有効になることはありません）、a `3`  / 404 は再試行してはいけませんが、a `1` 5xxレスポンスからのものは、バックオフ付き再試行の候補です。