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

# エラー

> 全エラーコードの意味と対処法

すべてのエラーは共通の形状を持ちます。

```json theme={null}
{
  "error": { "code": "not_found", "message": "Video not found" },
  "meta": { "request_id": "req_xxxxx" }
}
```

`error.code` は安定した機械判読用の文字列です。`error.message` は人間向けの説明で、バージョン間で変わる可能性があります。原則として `code` でパースし、`message` はログに残してください。

## エラーコード一覧

| コード                    | HTTP | 発生条件                                               | 推奨対応                                                           |
| ---------------------- | ---- | -------------------------------------------------- | -------------------------------------------------------------- |
| `unauthorized`         | 401  | `Authorization` ヘッダーが欠落・形式違反・無効                    | `Bearer lymo_...` 形式を確認。失効している場合は Web アプリで再発行                  |
| `invalid_key_metadata` | 401  | キーの署名は有効だが、Lymo 固有メタデータが欠落                         | Web アプリのキー発行フローから再発行してください                                     |
| `forbidden`            | 403  | キーがスコープ不足、または組織が非アクティブ                             | キーのスコープを確認。組織が有効なはずならサポートに連絡                                   |
| `not_found`            | 404  | リソース不在、または別組織に属する                                  | 下記「クロステナント 404」を参照                                             |
| `bad_request`          | 400  | ヘッダー形式違反（例: `Idempotency-Key` が 256 文字超過）          | ヘッダーを修正して再試行                                                   |
| `validation_failed`    | 422  | クエリ・ボディがスキーマ検証で失敗                                  | `message` で該当フィールドのパスを確認し、修正して再試行                              |
| `invalid_webhook_url`  | 422  | `POST /v1/webhooks` の配信先 URL が組織のホスト名許可リストに含まれていない | [Webhook → ホスト名の許可リスト](/guides/webhooks#登録前に確認-ホスト名の許可リスト) を参照 |
| `rate_limited`         | 429  | キーあたりのリクエスト数超過（下記の通り、現時点では適用されないキーもある）             | `Retry-After`（秒）に従い、以降は指数バックオフで調整                              |
| `service_unavailable`  | 503  | キー検証サービスが一時的に利用不可                                  | バックオフ付きで再試行。1 分以上続く場合はエスカレーション                                 |
| `internal_error`       | 500  | 予期せぬサーバエラー                                         | 1 度だけ再試行。継続するなら `request_id` を添えて報告                            |

## クロステナント 404

別組織に属するリソースは `403 forbidden` ではなく **`404 not_found`** を返します。これは意図的な挙動です。`403` を返すと ID の存在が漏洩するため、「存在しない」と区別のつかない `404` を返すことで ID 列挙攻撃を防いでいます。この挙動は動画だけでなく、すべてのリソースパスに適用されます。

具体例として、組織 A のキーで組織 B の動画 ID に対して `GET /v1/videos/{id}` を呼ぶと、以下が返ります。

```json theme={null}
{
  "error": { "code": "not_found", "message": "Video not found" },
  "meta": { "request_id": "req_xxxxx" }
}
```

存在するはずのリソースが 404 を返す場合、まずキーのスコープ先組織を疑ってください。想定と違う組織に発行されていることがよくあります。

```bash theme={null}
curl "$LYMO_BASE/v1/members/me" -H "Authorization: Bearer $LYMO_KEY"
```

返されたメンバーが所属する組織が、このキーからアクセスできる唯一の組織です。

## キーの自己失効

キーが漏洩した場合、Web UI にアクセスせずともキーの保持者自身で失効できます。

```bash theme={null}
curl -X DELETE "$LYMO_BASE/v1/keys/me" -H "Authorization: Bearer $LYMO_KEY"
# → { "data": { "revoked": true }, "meta": {...} }
```

このエンドポイントはスコープ不要です。どのキーも自身を失効させることができます。失効後、同じキーを使ったリクエストはすべて `401 unauthorized` を返します。

## `request_id` の使い方

すべてのレスポンス（成功・失敗にかかわらず）に `meta.request_id` が含まれます。問題を報告する際に添えていただくと、サーバ側で該当リクエストの正確なタイミング・入力・処理バックエンドを追跡できます。

```json theme={null}
{
  "error": { "code": "internal_error", "message": "An unexpected error occurred" },
  "meta": { "request_id": "req_fa29e58a3cfb4c0fbab0a75f82c4c7a3" }
}
```

形式は `req_` + 32 文字の小文字 16 進数（ハイフンを除いた UUID）です。同じ ID は `X-Request-Id` レスポンスヘッダーにも入るので、ログとの突き合わせが容易です。

## レート制限

レート制限は API キー単位で強制されます。超過時は `429 rate_limited` が返り、`Retry-After` ヘッダーに待機秒数が入ります。

```
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded" }, "meta": {...} }
```

<Note>
  現時点ではすべての発行済みキーにレート制限が適用されているわけではありません。将来のリリースでスコープごとの標準値が適用される予定です。`Retry-After` を常に尊重する設計にしておけば、制限適用への切り替え時にクライアント側の変更は不要になります。固定間隔をハードコードしないでください。
</Note>

## バリデーションエラー

`validation_failed`（422）は開発中に最も多く遭遇するエラーです。`message` にはフィールドパスが入ります。

```json theme={null}
{
  "error": {
    "code": "validation_failed",
    "message": "limit: Number must be less than or equal to 100"
  },
  "meta": { "request_id": "req_..." }
}
```

よくある原因:

* `limit` が `1–100` の範囲外（デフォルトは 25）
* `created_after` / `created_before` が ISO 8601 として不正
* `status` フィルタが許容 enum 外 — リソース別のステータス値は **APIリファレンス** タブを参照
* `POST /v1/webhooks` のボディで必須フィールドが欠落