APIキーの取得
UTAGE管理画面からAPIキーを発行します。- UTAGE管理画面にログイン
- 右上メニューの API設定 を開く
- 「追加」をクリック
- 管理名称を入力し、API利用ポリシーに同意して「保存」
- 表示されたAPIキーをコピーして安全な場所に保存
オペレーターのアカウントでは、契約者がオペレーター権限の「API設定」を「利用可」にしている場合だけ、右上メニューに API設定 が表示されます。
認証方法
全てのAPIリクエストにAuthorization ヘッダーでAPIキーを送信します。
curlでのテスト
401 Unauthorized エラーが返ります。error.code は常に unauthorized で、原因(APIキーの未指定・無効・無効化、アカウントの利用停止)は message で示されます。原因ごとの message はエラーハンドリングを参照してください。
エラーレスポンス例
アカウントが利用停止になると、利用停止日の当日0:00から、そのアカウントで発行した全てのAPIキー(MCP接続キーを含む)が使えなくなります。この場合の
message は「アカウントが利用停止されているためAPIキーを利用できません」です。リクエストの文字コード
リクエストボディは UTF-8 でエンコードしてください。UTF-8 以外の場合は400 invalid_encoding エラーが返ります。
セキュリティ
- APIキーはハッシュ化して保存されます。平文では保存されません
- 認証不要のエンドポイントを除く全てのAPIリクエスト(認証に失敗したものを含む)はログに記録されます
- 不要になったAPIキーは管理画面から無効化してください
レート制限
APIにはリクエスト数のレート制限があります。表の値は既定値で、契約内容により異なる場合があります。
分間の上限はAPIキー単位で数えます。日間の上限はアカウント単位で、同じアカウントで発行した全てのAPIキー(MCP接続キーを含む)のリクエストを合算して数えます。判定は分間 → 日間の順に行われます。
計測窓は固定窓です。最初のリクエストから60秒ではなく、毎分0秒(日間は毎日0:00)で必ずカウントがリセットされます。
レスポンスヘッダー
レート制限の対象エンドポイントのレスポンスには、次のヘッダーが含まれます。分間の残数と日間の残数はヘッダーには含まれません。次のエンドポイントはレート制限の対象外で、
X-RateLimit-Reset ヘッダーは付きません(X-RateLimit-Limit / X-RateLimit-Remaining は接続元IP単位の値が付きます)。- 認証不要のエンドポイント
- 読者作成(
POST /accounts/{account_id}/scenarios/{scenario_id}/readersおよびPOST /accounts/{account_id}/line/friends/{friend_id}/readers)。短時間に多数登録されるケースに対応するため分間・日間のレート制限を適用せず、代わりに後述のリソース作成上限(累計・1時間・月間)で制御されます
制限超過時
レート制限を超過すると429 Too Many Requests が返ります。
X-RateLimit-Reset は、超過した方の制限がリセットされる時刻を示します。
X-RateLimit-Limit と X-RateLimit-Remaining は超過時も接続元IP単位の制限の値のままで、超過した分間・日間の上限や残数 0 にはなりません。
配信予約時のキュー作成レート制限
上記のレート制限とは別に、配信メッセージを予約する操作にはシナリオ単位の制限があります。対象は次の操作です。- 配信メッセージ作成で
status=reservedを指定したとき - 配信メッセージ更新で下書き(
draft)を予約(reserved)に変えたとき、または予約中のメッセージの送信日時・条件などを変更して配信予約が再作成されるとき
429 が返り、details.retry_after(Y-m-d H:i:s)に現在の窓が終わる日時が入ります。この日時以降に再試行してください。
429 rate_limit_exceeded(message「同一シナリオで別の予約処理が実行中です。しばらく待ってから再試行してください。」)が返ります。この場合 details は付きません。少し待ってから再試行してください。
リソース作成上限
レート制限とは別に、データを作成するAPIにはAPI経由で作成できる件数の上限があります。上限値は契約内容により異なります。対象は次のエンドポイントです。
上限を超えると
429 が返ります。判定は累計 → 1時間 → 月間の順です。
details.resource_type には上の表のリソース種別が入ります。
契約内容による件数上限(ファネル・ステップ・配信アカウント・シナリオ・商品・会員サイト・コース・レッスン)は上記とは別の仕組みで、
422 plan_limit_exceeded または 400 bad_request が返ります。詳細はエラーハンドリングを参照してください。認証不要のエンドポイント
以下の参照系エンドポイントは、APIキーなしで利用できます。レート制限の対象外で、X-RateLimit-Reset ヘッダーは付きません。