エラー
エラーは OpenAI 互換の形 {"error": {"code": "..."}} です。code で分岐してください。bearer 経路の 400 には message（破った規則）と type: invalid_request_error が付きます。下の表は edge が返す全 code を、返すコードから生成しています。
{"error": {"code": "invalid-research-request",
"message": "max_tokens: 1..32768",
"type": "invalid_request_error"}}| HTTP | code | いつ | 対処 |
|---|---|---|---|
| 400 |
invalid-json
|
本文が JSON として読めない、または空。 | content-type: application/json と正しい JSON を送る。 |
| 400 |
invalid-research-request
|
リクエストが admission の形に合わない。bearer 経路では error.message が破った規則を名指しする（例: "max_tokens: 1..32768"）。 | message を読んで直す。unknown parameter は落とすか、ignorable な名前に。 |
| 400 |
invalid-job-id
|
/v1/research/jobs の idempotency-key（または jobId）が v4 UUID でない。 | UUID v4 を使う。 |
| 400 |
invalid-application
|
研究者登録の申請本文が不正。 | verificationMode / consent / purpose / scope を揃える。 |
| 400 |
invalid-ekyc-request
|
本人確認の開始本文が不正（scopeId / tasks）。 | アカウントコンソールから開始する。 |
| 401 |
sign-in-required
|
cookie セッションも有効な PAT も無い。 | Authorization: Bearer kc_pat_… を付ける。 |
| 401 |
token-revoked
|
取り消された（または登録の無い）トークン。 | アカウントコンソールで新しいトークンを発行する。 |
| 403 |
origin-not-allowed
|
ブラウザからの POST が許可外の Origin。 | kotoba.cloud 上のページから呼ぶか、PAT を使う。 |
| 403 |
research-access-denied
|
PAT の検証に失敗、または authority が 403 で拒否（本人確認・スコープ以外の理由）。 | トークンを確認し、/v1/research/status で状態を見る。 |
| 403 |
verification-required
|
本人確認（カード）が未完了または期限切れ（レッドチームのみ）。 | アカウントコンソールの本人確認を完了する。 |
| 403 |
verification-expired
|
本人確認が 365 日を過ぎた。 | 再確認する。 |
| 403 |
trust-route-required
|
現在の信頼経路が無い。 | 本人確認をやり直す。数秒後の再試行で解けることもある。 |
| 403 |
screening-expired
|
AML/CTF 照合が 24 時間を過ぎた。 | 再審査を待つ。 |
| 403 |
review-required
|
審査中、または追加確認が必要。 | アカウントコンソールの案内に従う。 |
| 403 |
policy-acceptance-required
|
利用ポリシーの版が変わり、再同意が必要。 | アカウントコンソールで同意する。 |
| 403 |
session-reverification-required
|
継続セッションの証跡が古い。 | ページを再読み込みするか、PAT で再試行。 |
| 403 |
identity-mismatch
|
記録の principal と一致しない。 | support@kotoba.cloud に連絡。 |
| 403 |
research-scope-required
|
task が承認済みスコープに含まれない。 | code-review は本人確認と同時に承認される。他はスコープ申請。 |
| 403 |
model-route-not-configured
|
カタログにあるが経路の無いモデル。無料枠は消費しない。 | /v1/models の availability が served のモデルを使う。 |
| 403 |
guardrail-blocked
|
内容ポリシー（CSAM・CBRN・大規模詐欺）。耐久レシートに残る。 | 再送しない。 |
| 403 |
firewall-denied
|
そのタスク種別が現在の assurance rung では閉じている。 | 標準 3 タスクを使うか、rung を上げる。 |
| 403 |
job-reverification-required
|
ジョブの poll 時に ladder の再検証に失敗。 | /v1/research/status で理由を確認。 |
| 403 |
prepaid-card-not-accepted
|
本人確認でプリペイド／バーチャルカード。 | クレジットまたはデビットカードで。 |
| 404 |
job-not-found
|
その jobId のジョブが無い（別 principal のものも含む）。 | 作成時の id を使う。 |
| 405 |
method-not-allowed
|
経路に対して method が違う。/v1/messages・/v1/responses・Gemini wire もここ（提供なし）。 | OpenAI の chat.completions wire を使う。 |
| 409 |
idempotency-conflict
|
同じ job id に別の入力。 | 入力が変わるなら新しい id。 |
| 413 |
body-too-large
|
本文が 2 MiB を超えた。 | 入力を 524,288 文字以内に。 |
| 415 |
json-required
|
content-type が application/json でない。 | ヘッダを付ける。 |
| 429 |
free-quota-exhausted
|
無料枠 1,000 件/日を使い切った（UTC 深夜にリセット、Retry-After なし）。残高があれば有料で走る。 | 翌日（UTC）か、credits を足す。 |
| 502 |
inference-failed
|
推論の実行が失敗（上流の拒否・エラー）。有料の予約は解放される。 | 再送する。続くなら status ページと support。 |
| 502 |
invalid-inference-receipt
|
ジョブは succeeded だが本文も tool_calls も無い。 | 再送する。 |
| 502 |
invalid-job-receipt
|
authority の応答が契約の形でない。 | 再送する。続くなら support。 |
| 503 |
research-service-unavailable
|
authority に到達できない、または名前の無い失敗。 | 少し待って再送。 |
| 503 |
verification-provider-not-configured
|
この環境に研究 authority が無い。 | 本番 api.kotoba.cloud を使う。 |
| 503 |
pat-not-configured
|
この環境に PAT の署名鍵が無い。 | 本番 api.kotoba.cloud を使う。 |
| 503 |
card-verification-not-configured
|
本人確認の決済側が一時的に利用不可。 | 後で再試行。 |
| 504 |
inference-timeout
|
サーバ側の待ち（14 分）を超えた。ジョブは続いている。 | 同じリクエストを再送すると同じジョブに再接続する。 |
ガードレールとファイアウォールの 403 は耐久レシートとして残ります。429 は UTC 深夜にリセットされ Retry-After は付きません。有料の応答にはエラーではなく settlement: "pending" が付くことがあります（Per-request cost）。