> ## Documentation Index
> Fetch the complete documentation index at: https://help.comdesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# エラー

> 統一されたエラーエンベロープ、すべてのエラーコード、X-Request-ID を用いたデバッグ方法。

すべてのエラーは単一の JSON エンベロープを共有するため、クライアント側で統一的に処理できます。

## エラーエンベロープ

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "details": null
  }
}
```

| フィールド | 説明 |
| - | - |
| `code` | 安定した機械可読のエラーコード（分岐はこれで行う） |
| `message` | 人間向けの説明（解析しないこと） |
| `details` | 該当する場合のフィールド別バリデーションエラー、なければ `null` |

`422 validation_error` の場合、`details` に問題のフィールドが入ります：

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The request payload failed validation.",
    "details": {
      "phone_number": ["The phone_number format is invalid."],
      "staff_id": ["The selected staff_id is invalid."]
    }
  }
}
```

## エラーコード

| ステータス | コード | 意味 | 対処 |
| - | - | - | - |
| 401 | `invalid_api_key` | キーが欠落・不正・失効 | `Authorization` ヘッダーを確認。失効ならローテーション |
| 401 | `expired_api_key` | キーが有効期限切れ | 管理者に新しいキーの発行を依頼 |
| 403 | `insufficient_scope` | キーに必要なスコープがない | 管理者にスコープの追加を依頼 |
| 403 | `ip_not_allowed` | 送信元 IP が許可リストにない | サーバー IP を許可リストに追加 |
| 404 | `resource_not_found` | ID が存在しない／自テナント外 | ID が自テナントのものか確認 |
| 422 | `validation_error` | バリデーション失敗 | `details` を確認し、該当フィールドを修正 |
| 429 | `rate_limit_exceeded` | 当該分のリクエスト過多 | `Retry-After` 後にバックオフして再試行 |
| 429 | `quota_exceeded` | 日次・月次クォータ枯渇 | リセットを待つか Comdesk に連絡 |
| 500 | `internal_error` | サーバー側エラー | `X-Request-ID` を記録しサポートに連絡 |

## X-Request-ID でのデバッグ

すべてのレスポンスには `X-Request-ID` ヘッダー（そのリクエスト固有の UUID v4）が含まれます。独自の `X-Request-ID` を**送信**すると、Comdesk はそれをそのまま返すため、自社ログと Comdesk のログを相関できます。

```text theme={null}
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
```

<Note>
  エラーが発生したら、レスポンスの `X-Request-ID` を控えてください。同じ ID は **設定 → Open API → 利用ダッシュボード → 直近のリクエストログ** で確認でき、サポートはエンドツーエンドで追跡できます。これにより調査が桁違いに速くなります。
</Note>