kintone API上限の設計方法｜10,000回・同時接続100を超えない連携構成

kintoneを外部システムとつなぐとき、API上限は後から効いてきます。

最初は問題なく動きます。

フォームからkintoneへ登録する。

会計システムへ請求情報を送る。

ECの注文をkintoneへ取り込む。

在庫情報を夜間に同期する。

kintoneのレコードを外部DBへ出す。

Slackやメールへ通知する。

こうした連携は、件数が少ないうちは気づきません。

しかし、対象アプリやレコード数が増えると、次のような問題が出ます。

• 毎回全件取得していて、1日あたりのAPIリクエスト数が増える
• 複数のバッチが同じ時間帯に走り、同時接続が増える
• ユーザー操作時にJavaScriptカスタマイズがAPIを大量に呼ぶ
• Webhookを受けた外部処理が、kintoneへ即時更新を連打する
• Bulk Requestを使っているのに、回数削減できていると誤解する
• 429エラー時に同じ処理をすぐ再試行し、さらに詰まる
• 失敗ログがなく、どのレコードまで処理したか分からない
• 日次上限に近づいても、運用側が気づけない

API上限は、開発者だけの話ではありません。

どの業務を即時反映するか。

どの業務は夜間でよいか。

どのアプリを外部連携の起点にするか。

どのデータをkintone内に残し、どのデータを外部DBへ逃がすか。

こうした業務設計の判断と直結します。

kintone API上限は、数値を暗記するものではなく、連携方式・処理時間帯・再実行方法を決めるための設計条件です。

この記事では、kintone APIの上限値、1日あたりのAPIリクエスト数と同時接続100の違い、Bulk Requestの考え方、全件同期を避ける方法、キュー・夜間バッチ・リトライ、429エラー時の監視ログ、外部DBやETLへ逃がす判断を整理します。

kintoneレコード数上限の考え方はこちら
kintoneフォーム連携の設計方法はこちら

先に結論：API上限は連携方式で吸収する

kintone API上限への対策は、「上限に近づいたら考える」では遅いです。

連携を作る時点で、次を決めます。

設計項目	決めること
同期方式	全件同期か、差分同期か
実行タイミング	即時、数分ごと、夜間、手動実行
同時実行	何ジョブまで並列に動かすか
更新単位	1件ずつ、100件単位、Bulk Request
失敗時	すぐ再試行、時間を空けて再試行、手動確認
ログ	成功、失敗、対象件数、エラーコード、再実行可否
運用	誰が失敗を確認し、誰が再実行するか
退避	kintoneに残すか、外部DBやETLに分けるか

API上限で起きる問題の多くは、kintoneの仕様そのものより、連携方式の設計不足から起きます。

特に危ないのは、次の3つです。

危ない設計	起きること
毎回全件取得	レコード数が増えるほどAPIリクエスト数が増える
並列処理の上限なし	同時接続100に近づき、429エラーが出る
失敗時に即時リトライ	混雑時にさらにリクエストを増やす

一方、最初から次のようにしておくと、件数が増えても運用しやすくなります。

良い設計	具体例
差分同期	更新日時、ステータス、同期済みフラグで対象を絞る
キュー処理	受付とAPI更新を分け、順番に処理する
同時実行制御	ワーカー数を決め、上限に近いときは待つ
時間帯分散	日中の即時処理と夜間バッチを分ける
ログ保存	処理ID、対象アプリ、対象件数、結果、エラーを残す
再実行UI	失敗したレコードだけ再処理できるようにする

API上限対策の中心は、APIを速く連打することではなく、呼ばなくてよいAPIを減らし、呼ぶAPIを順番に流すことです。

公式のAPI上限値を整理する

kintoneのREST APIには、複数の制限があります。

まず、同時アクセス数です。

kintoneヘルプの制限値一覧では、REST APIの同時アクセス数は1つのドメインにつき100までとされ、上限を超えるとHTTPステータスコード429が返ると説明されています。

同じページでは、リクエストボディのサイズは50MBまで、アップロードしたファイルはレコード登録APIやレコード更新APIでレコードに添付しない限り3日間で削除されることも説明されています。

kintoneヘルプ：制限値一覧

次に、1日に実行できるAPIリクエスト数です。

この上限は契約コースによって異なります。

kintoneの料金ページでは、1アプリごとのAPIリクエスト数として、スタンダードコースは1万/日、ワイドコースは10万/日と案内されています。

kintone：料金

整理すると、少なくとも次を見ます。

種類	公式情報で確認する値	設計で見ること
同時アクセス数	1ドメイン100まで	同じ時間帯に何本の処理が走るか
日次APIリクエスト数	コース別。スタンダードは1アプリ1万/日、ワイドは10万/日	1日合計で何回APIを実行するか
リクエストボディ	50MBまで	大きなJSONや一括更新を詰め込みすぎないか
アップロード済みファイル	レコードに添付しない限り3日で削除	ファイルAPIとレコード登録/更新を分けて失敗しないか
レコード一括操作	登録・更新・削除は一度に100件まで	100件単位の分割とログを作るか
Bulk Request	1回に含めるリクエストは最大20件	まとめる目的を誤解していないか

cybozu developer networkのkintone REST API共通仕様では、レコード操作APIについて、複数レコードを取得するAPIのoffset指定は10,000件まで、登録・更新・削除を一度に指定できるレコード数は100件までと説明されています。

cybozu developer network：kintone REST APIの共通仕様

API上限を見るときは、「1日1万回」だけを見ない方がよいです。

1日回数は足りていても、同時接続で429になることがあります。

同時接続は問題なくても、毎日リクエスト数が増え続け、後からアプリ構成を変えざるを得ないことがあります。

リクエスト数は少なくても、1回の処理が重く、処理時間が伸びることもあります。

1日10,000回と同時接続100の違い

1日あたりのAPIリクエスト数と、同時接続100は別の制限です。

混同すると、原因調査を間違えます。

観点	1日あたりのAPIリクエスト数	同時接続100
単位	アプリごと	ドメインごと
期間	日本時刻9:00から翌8:59	その瞬間の同時実行
典型的な原因	全件同期、頻繁なポーリング、画面表示時API	並列バッチ、短時間の大量処理、重い処理の重なり
気づき方	アプリ管理画面、超過メール	429エラー、レスポンスヘッダー、同時接続数API
対策	API回数を減らす、差分取得にする	並列数を絞る、キューで待たせる

cybozu developer networkの記事では、APIリクエスト数はkintone REST APIを1回実行するごとに1リクエストとしてカウントされ、アプリごとにカウントされると説明されています。

また、アプリ管理画面のAPIリクエスト数は、日本時刻で毎日午前9時にリセットされます。

cybozu developer network：kintone APIリクエスト数の超過メールが届いたら？

たとえば、スタンダードコースで1アプリ1万/日を前提にするなら、次のように粗く見積もれます。

処理	1回あたり	実行回数	1日リクエスト数
10分ごとの差分取得	2回	144回	288回
夜間の100件単位更新	100回	1回	100回
ユーザー操作時の参照	1回	2,000回	2,000回
Webhook後の更新	2回	1,500件	3,000回
失敗リトライ	1回	500件	500回
合計			5,888回

この例では、1万/日にはまだ余裕があります。

しかし、ユーザー操作時の参照が1回ではなく5回、Webhook後の更新が2回ではなく6回になると、すぐに上限へ近づきます。

同時接続は、合計回数ではなく「同じ瞬間に何本が動くか」です。

たとえば、夜間0時に次の処理が同時に始まるとします。

処理	並列数
EC注文取込	20
在庫同期	30
会計連携	20
レポート用抽出	20
ユーザーの画面操作	15
合計	105

この場合、1日の合計回数が少なくても、同時アクセス数100にぶつかる可能性があります。

同時接続100はドメイン単位なので、1つのアプリだけの問題ではありません。

別アプリの処理、ユーザー操作、カスタマイズ、外部連携が重なります。

1日10,000回は「総量」の制限、同時接続100は「瞬間最大」の制限です。前者は回数設計、後者は並列数と時間帯の設計で対処します。

Bulk Requestは回数削減の魔法ではない

Bulk Request APIは、複数アプリのレコード操作をまとめて実行できるAPIです。

cybozu developer networkでは、Bulk Request APIに含められるリクエストの最大数は20件で、いずれかのAPIが失敗した場合はすべての操作がロールバックされると説明されています。

cybozu developer network：複数アプリのレコード操作を一括処理する

一方で、kintoneヘルプの制限値一覧では、/k/v1/bulkRequest.jsonで複数のAPIを実行した場合、実行したAPIそれぞれがリクエスト数にカウントされると説明されています。

kintoneヘルプ：制限値一覧

つまり、Bulk Requestの使い道はこうです。

目的	向いているか	理由
複数操作をまとめて成功/失敗させる	向いている	途中失敗時にまとめて戻せる
APIの往復回数を減らす	場合による	HTTPリクエストとしてはまとめられる
1日あたりのAPIカウントを大幅に減らす	向いていない	内包したAPIそれぞれがカウントされる
複数アプリをまたぐ整合性を取りやすくする	向いている	関連する更新をまとめられる

Bulk Requestを使うべき場面は、回数削減より整合性です。

たとえば、次のような処理です。

処理	Bulk Requestを使う理由
案件作成と関連タスク作成	片方だけ成功すると困る
在庫引当と履歴登録	在庫だけ変わり履歴が残らない事故を避ける
請求レコード更新と連携ログ登録	請求だけ変わりログがない状態を避ける
受付レコード更新とステータス変更	処理済み状態とデータ更新をそろえる

逆に、単に大量更新したいだけなら、Bulk Requestだけでは足りません。

100件単位の更新、20リクエスト単位のまとめ、失敗時のロールバック、日次カウント、同時接続を合わせて設計します。

全件同期ではなく差分同期にする

API上限を守るうえで、一番大きいのは全件同期をやめることです。

全件同期は、最初は楽です。

しかし、レコードが増えるほど負荷が増えます。

件数	全件取得を毎時行う場合	1日24回の実行
1,000件	軽く見える	24回分の取得
10,000件	取得条件やページングが必要	24回分の取得
100,000件	処理時間が伸びる	毎日大きな負荷
500,000件	運用上かなり重い	他処理とぶつかりやすい

差分同期では、前回処理した時点から変わったレコードだけを対象にします。

使う条件は業務によって変えます。

差分条件	向いている場面	注意点
更新日時	一般的な更新同期	どの更新も拾うため、不要変更も対象になる
作成日時	新規登録だけ取り込む	更新は拾えない
ステータス	承認済み、送信待ちなど	状態遷移の運用が必要
同期済みフラグ	外部送信の完了管理	失敗時にフラグを変えない設計が必要
外部ID	外部システムとの突合	重複と採番ルールが必要
連携対象チェック	手動で対象を選ぶ	押し忘れ、解除忘れに注意

差分同期では、処理ログが重要です。

「前回どこまで処理したか」をログに残します。

ログ項目	目的
処理ID	1回の実行を識別する
対象アプリID	どのアプリを処理したか
開始時刻/終了時刻	処理時間と重なりを確認する
検索条件	どの差分条件で取ったか
対象件数	予定件数を把握する
成功件数	正常に終わった数を確認する
失敗件数	再実行対象を把握する
最終処理キー	次回の起点にする
エラーコード	原因を分類する

「更新日時 > 前回実行時刻」だけにすると、境界時刻の取りこぼしが起きることがあります。

そのため、実装では少し重ねて取得し、処理IDや外部IDで重複を吸収する形にします。

たとえば、前回が10:00までなら、次回は9:55以降を取得し、すでに処理済みのレコードはスキップする、という考え方です。

キュー・夜間バッチ・リトライを設計する

API連携は、受付と処理を分けると安定します。

フォーム送信やWebhookを受けた瞬間に、kintone APIを連打しない方がよい場面があります。

代わりに、キューへ積みます。

構成	役割
受付処理	外部イベントを受け取り、処理対象を登録する
キュー	順番、優先度、再実行回数を持つ
ワーカー	決めた並列数でkintone APIを実行する
リトライ	429や一時エラー時に時間を空けて再実行する
失敗箱	手動確認が必要なものを分ける
管理画面	再実行、停止、除外を行う

この構成にすると、同時接続を制御しやすくなります。

たとえば、ワーカー数を5にすれば、同時にkintoneへ投げる処理を5本に抑えられます。

混雑時間帯は2本にし、夜間は10本に増やす、といった制御もできます。

ただし、夜間バッチにも注意があります。

夜間にすべてを集めると、0時、1時、3時などに処理が集中します。

社内の別システムも同じ時間帯にバッチを走らせることがあります。

時間帯	設計例
日中	画面操作に必要な最小限の即時処理
夕方	当日分の軽い差分同期
夜間前半	会計、在庫、注文など締め処理
夜間後半	レポート、外部DB、バックアップ系
早朝	処理結果の確認と通知

リトライも設計します。

429エラーが出たときに、すぐ同じ処理を繰り返すと逆効果です。

エラー	再実行方針
429	時間を空け、並列数を下げて再試行
5xx	一時障害として段階的に再試行
400系の入力エラー	データ修正が必要なので自動再試行しない
認証エラー	トークン、権限、IP制限を確認する
レコード競合	最新revision確認後に再処理する

再実行回数も無制限にしません。

たとえば、1分後、5分後、30分後に再試行し、それでも失敗したら失敗箱へ移す、という形です。

kintoneセキュリティの設計方法はこちら

429エラーと監視ログを見る

429エラーは、同時アクセス数が上限を超えたときに返ります。

cybozu developer networkの同時接続数に関する記事でも、同時接続数が100を超えるとREST API実行時にHTTPステータスコード429が返り、同時接続数が100を下回らない限りAPIリクエストが通らない状態になると説明されています。

cybozu developer network：kintone REST API同時接続数の制限値はなぜあるのか

また、REST API共通仕様では、レスポンスヘッダーとして同時接続数の上限値を示すX-ConcurrencyLimit-Limit、現在の同時接続数を示すX-ConcurrencyLimit-Runningが説明されています。

cybozu developer network：kintone REST APIの共通仕様

連携側では、少なくとも次をログに残します。

ログ	見ること
HTTPステータス	429、400、401、403、5xxを分ける
エラーコード	kintone側のエラー種別を確認する
対象アプリ	どのアプリの処理で起きたか
対象レコード	どのレコードで止まったか
リクエスト種別	取得、登録、更新、削除、Bulk Request
実行時刻	同じ時間帯に処理が集中していないか
処理時間	重いAPIがないか
同時接続数	上限に近づいていないか
再試行回数	失敗を繰り返していないか

監査ログも使います。

cybozu developer networkの記事では、監査ログでAPIを使用した操作履歴を確認でき、レコード登録や更新などの操作ログからAPIリクエスト数増加の原因を特定できる可能性がある一方、レコード取得などの操作ログは出力されないため注意が必要と説明されています。

cybozu developer network：kintone APIリクエスト数の超過メールが届いたら？

ログで重要なのは、障害時だけではありません。

平常時から、日別・時間帯別・アプリ別の傾向を見ます。

指標	危険な兆候
日次APIリクエスト数	毎月増え続けている
時間帯別件数	0時、9時、18時に集中している
429件数	一時的でなく継続して出ている
リトライ件数	失敗後の再実行が多い
取得API件数	画面表示やポーリングで増えている
更新API件数	同じレコードを何度も更新している

API上限の運用では、エラー発生後の調査だけでなく、日別・時間帯別・アプリ別の増え方を見て、処理方式を早めに変えます。

外部DBやETLへ逃がす判断

kintone API連携をすべてkintone中心にすると、無理が出ることがあります。

特に次の用途です。

用途	kintoneだけで抱えにくい理由
大量ログ保存	APIログや操作履歴が急速に増える
横断集計	複数アプリを何度も取得する必要がある
BI連携	ダッシュボード更新のたびにAPI取得が増える
外部検索	複雑な条件検索を高頻度で行う
データ加工	kintone側で計算や整形が重くなる
長期保管	現役アプリの表示や検索に影響する

この場合、kintoneは業務入力・状態管理の場として使い、分析や検索は外部DBやETLへ分ける方が安定します。

kintoneに残す	外部に分ける
現在進行中の案件	過去数年分の履歴
担当者が編集するレコード	BI用の正規化データ
承認やステータス管理	ログ、スナップショット
現場で確認する一覧	横断検索、重い集計
差し戻しやコメント	分析用の加工済みテーブル

kintoneデータベース設計はこちら
kintone集計の設計方法はこちら

外部DBへ出す場合でも、全件同期を前提にしません。

初回だけ全件移行し、その後は差分で追います。

レコードID、revision、更新日時、外部ID、処理ログを使い、取りこぼしと重複を吸収します。

設計項目	決めること
初回移行	いつ、どの範囲を全件取得するか
差分条件	更新日時、作成日時、ステータス、フラグ
重複判定	レコードID、外部ID、revision
削除反映	物理削除を追うか、削除フラグで運用するか
権限	外部DB側で誰が見られるか
ログ	kintone取得、外部保存、失敗、再実行

外部DBやETLに逃がす判断は、kintoneをやめる判断ではありません。

kintoneを、現場が使う入力・確認・承認の場として保つための分担です。

実装前チェックリスト

kintone API連携を作る前に、次を確認します。

チェック	内容
対象アプリ	どのアプリIDに対してAPIを実行するか
契約コース	日次APIリクエスト数の上限がいくつか
現在のAPI使用量	アプリ管理画面で日次件数を確認したか
対象件数	1回、1日、1か月で何件扱うか
同期方式	全件ではなく差分にできるか
実行時間帯	他バッチや利用者操作と重ならないか
並列数	ワーカー数や同時実行数を決めたか
リトライ	429時に間隔を空けるか
ログ	成功、失敗、再実行可否を残すか
再実行	失敗レコードだけ再処理できるか
Bulk Request	整合性目的で使うか、回数削減と誤解していないか
ファイルAPI	アップロード後3日以内にレコードへ添付するか
権限	APIトークン、ユーザー権限、IP制限を確認したか
退避	大量ログやBI用データを外部へ分けるか

API連携の設計書には、APIのURLやパラメータだけでなく、次も書きます。

設計書に書くこと	理由
日次API見積もり	上限に対して余裕があるか判断する
同時実行見積もり	429リスクを見る
実行スケジュール	バッチ集中を避ける
エラー分類	自動再実行と手動確認を分ける
処理ログ仕様	障害時に再実行できるようにする
運用担当	誰が失敗を確認するか決める
変更時の影響	アプリ追加や連携追加で上限に近づかないか見る

Bitlightに相談できること

kintone API連携は、APIを呼ぶコードだけ作っても安定しません。

実務で止まりにくくするには、連携対象、差分条件、処理タイミング、並列数、ログ、再実行、権限、外部DBとの分担まで決める必要があります。

Bitlightでは、既存のkintoneアプリと外部システムを見ながら、次のような設計を支援できます。

• 現在のAPIリクエスト数と連携処理の棚卸し
• 全件同期を差分同期へ変える設計
• キュー、ワーカー、夜間バッチ、リトライの設計
• 429エラー時のログ、通知、再実行UIの設計
• APIトークン、IP制限、権限設計の見直し
• kintoneに残すデータと外部DBへ分けるデータの整理
• CSV/API/プラグイン/外部連携サービスの使い分け

API上限は、超えてから直すと影響範囲が広くなります。

処理が増える予定があるなら、先にAPIリクエスト数、同時接続、ログ、再実行を見える形にしておく方が安全です。