エラー
javinfo API が返す HTTP ステータスコードとエラーボディ。
失敗したリクエストは課金されません。支払うのは成功した 200 だけです。
ステータスコード
| ステータス | 意味 |
|---|---|
400 | 不正なリクエスト。入力検証の失敗（必須パラメータの欠落、範囲外の値、不正な enum）、/query または /idols に q もフィルターもない、プロバイダー ID が不明。 |
401 | API キーがない、または無効。 |
402 | クレジット不足。Retry-After は1時間。自動化クライアント向けのヒントで、チャージすればすぐ解除。 料金を参照。 |
404 | 結果なし。/movie、/random、/idols/{id}、/discover/similar、/analytics/idols/* のルックアップ、/resolve、/resolve/provenance、/resolve/streams が返します。 |
422 | /query のみ：そのフィルター/ソートに対応するプロバイダーがない、ピン留め先が非対応、q なしで50ページ超え。 フィルタリングを参照。 |
429 | リクエスト過多：アカウントの1分あたりの上限か、ライブプロバイダーの時間あたりの枠。Retry-After の分だけ待つ。 |
503 | providers= で固定したプロバイダーが時間枠超過。固定を外せば別のソースから応答。または Retry-After の分だけ待つ。 |
499 | プロバイダーの応答前にクライアントが閉じた。 |
/query は 404 を返しません。一致なしは count: 0 と空の results を持つ 200 で、
課金なし — count を見てください。名前付きルックアップ（/idols/{id}、
/discover/similar、resolve）は品番や出演者がなければ 404 を返します。
エラーボディ
ハンドラーのエラーは oRPC のエンベロープで、defined、code、status、message を持ちます：
{
"defined": false,
"code": "NOT_FOUND",
"status": 404,
"message": "no title found for \"ZZZZ-99999\""
}400 は data.issues を追加し、失敗したルールごとに1件：
{
"defined": false,
"code": "BAD_REQUEST",
"status": 400,
"message": "Input validation failed",
"data": {
"issues": [
{
"expected": "string",
"code": "invalid_type",
"path": ["q"],
"message": "Invalid input: expected string, received undefined"
}
]
}
}422：同じエンベロープで status: 422、code: "BAD_REQUEST"：
{
"defined": false,
"code": "BAD_REQUEST",
"status": 422,
"message": "does not support sort \"rating\""
}ゲートでの拒否は、ハンドラーに届く前なので短くなります：
{ "error": "invalid api key" }キーがない場合はゲートを通り、ハンドラーが oRPC の UNAUTHORIZED ボディで拒否します：
{
"defined": false,
"code": "UNAUTHORIZED",
"status": 401,
"message": "Unauthorized"
}1分あたりのリミッターも短い形です：{ "error": "rate limit exceeded" }。
code が常にあるとは限りません — ステータスで分岐し、詳細はボディから。
バックオフ
429、402、503 は秒単位の Retry-After を伴います。従ってください：
if ([429, 402, 503].includes(res.status)) {
const wait = Number(res.headers.get('Retry-After') ?? 1);
await new Promise((r) => setTimeout(r, wait * 1000));
}402 の1時間は目安です。人が見ているなら、チャージすればすぐに再試行できます。