プラットフォーム API のエラーと制限

プラットフォーム API のエラーはモデルエンドポイントのエラーとボディ形式が異なります。HTTP ステータスコードが結果を表し、JSON ボディには常に success が、失敗時には機械可読な code が含まれます。

レスポンス形式

成功時は HTTP 200 を返します。

{
  "success": true,
  "message": "",
  "data": {}
}

失敗時は実際の HTTP ステータスコードを使用し、レスポンスボディに機械可読な code が含まれます。

{
  "success": false,
  "message": "Invalid Management Key",
  "code": "invalid_token"
}

message はローカライズされた文言で、バージョンによって変わる可能性があります。プログラムでの判定には HTTP ステータスコードと code を使用してください。

エラーコード

HTTP	code	シナリオ
400	invalid_request	パラメーター不正。金額の範囲外、作成時の名前の欠落または長すぎる名前、status が 1 / 2 以外、期限切れまたは利用可能額を使い切った Key の有効化、不正な有効期限、不正なページネーションまたは時間範囲、クエリ内の未エンコードの ; など
401	invalid_token	Authorization ヘッダーがない、形式が不正、キーが存在しないか削除済み
401	token_expired	マネジメントキーの有効期限が切れている
401	token_revoked	マネジメントキーが失効している（既存のキーのみ。新規作成したキーは削除のみ可能）
403	user_disabled	マネジメントキー所有ユーザーが無効化されている
403	insufficient_scope	マネジメントキーがこのエンドポイントに必要な権限を持っていない
404	not_found	API Key が存在しないか、あなたのものではない（両者は区別されません）、または /api/open/v1 配下に存在しないパス
405	method_not_allowed	パスは存在するが、その HTTP メソッドをサポートしていない
429	rate_limited	マネジメントキーごとのレート制限を超過
500	internal_error	サーバーエラー。内部の詳細は返されません

/api/open/v1 配下の未知のパスは 404、誤った HTTP メソッドは 405 を返し、どちらも上記の統一エラーボディを使用します。code で「別のメソッドで再試行する」のか「パスやパラメーターが誤っている」のかを判別できます。

レート制限

範囲	制限	対象	超過時のレスポンス
マネジメントキーごと	120 回/分	すべてのプラットフォーム API エンドポイント	429、code は rate_limited
ユーザーごと	30 回/分（デフォルト）	アカウントログ、ログのエクスポート、使用量統計、モデル別使用量、Key 別使用量	429、レスポンスボディが空の場合あり
クライアント IP ごと	180 回/180 秒（デフォルト）	すべての /api エンドポイントで共有	429
クライアント IP ごと	100 回/20 分（デフォルト）	API Key の完全な値を取得する などの機密性の高いエンドポイント	429、レスポンスボディが空の場合あり

レート制限は HTTP ステータスコードで処理してください。429 を受け取った場合は頻度を下げ、しばらくしてから再試行してください。

モデルエンドポイントは別のエラー形式と独自の制限を使用します。よくあるエラー を参照してください。