Skip to main content

APIキーの取得

UTAGE管理画面からAPIキーを発行します。
  1. UTAGE管理画面にログイン
  2. 右上メニューの API設定 を開く
  3. 「追加」をクリック
  4. 管理名称を入力し、API利用ポリシーに同意して「保存」
  5. 表示されたAPIキーをコピーして安全な場所に保存
オペレーターのアカウントでは、契約者がオペレーター権限の「API設定」を「利用可」にしている場合だけ、右上メニューに API設定 が表示されます。
APIキーは発行時に一度だけ表示されます。紛失した場合は新しいキーを発行してください。

認証方法

全てのAPIリクエストに Authorization ヘッダーでAPIキーを送信します。

curlでのテスト

認証に成功するとAPIレスポンスが返ります。失敗した場合は 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-Limit と X-RateLimit-Remaining は現在、APIキー単位の分間上限・残数ではなく、接続元IP単位の制限の値を示します。分間上限の情報はヘッダーでは X-RateLimit-Reset だけです。
次のエンドポイントはレート制限の対象外で、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 にはなりません。
X-RateLimit-Reset ヘッダーの時刻まで待ってからリトライしてください。

配信予約時のキュー作成レート制限

上記のレート制限とは別に、配信メッセージを予約する操作にはシナリオ単位の制限があります。対象は次の操作です。
  • 配信メッセージ作成で status=reserved を指定したとき
  • 配信メッセージ更新で下書き(draft)を予約(reserved)に変えたとき、または予約中のメッセージの送信日時・条件などを変更して配信予約が再作成されるとき
読者数が多いシナリオでは、キュー作成の回数が固定窓で数えられます。窓の長さは読者数に応じて決まり、1つの窓で作成できる回数に上限があります。超過すると 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 ヘッダーは付きません。