kintone API制限の回避設計｜429・同時接続・バッチ処理で詰まらない方法

kintone API制限で困るとき、現場では「APIが止まった」「429が出た」「夜間バッチが終わらない」という形で表面化します。

しかし、原因は1つではありません。

一括更新が大量に走っている。

画面カスタマイズが一覧表示のたびにAPIを呼んでいる。

定期同期が全件取得になっている。

帳票生成の前処理で複数アプリを取得している。

添付ファイルを1件ずつ処理している。

Webhookを受けた外部処理が、kintoneへ即時更新を連打している。

夜間0時に複数の処理を同時に開始している。

どれも、最初は問題なく動きます。

件数が少ないうちは、制限に当たりません。

ところが、レコード数、利用者数、連携先、処理頻度が増えると、急に詰まります。

このとき、単純にリトライ回数を増やすと、むしろ悪化することがあります。

混雑しているところへ、失敗した処理をさらに投げ直すからです。

kintone API制限の回避は、エラー後にリトライを増やす作業ではなく、制限に当たりやすい処理を分割し、流量を制御する設計です。

この記事では、kintone API制限で429が起きる代表パターン、同時接続数の監視、全件処理の分割、差分同期、実行時間帯、Bulk Requestの注意点、リトライ・バックオフ・失敗ログ、外部基盤へ逃がす判断を整理します。

kintone API上限の設計方法はこちら
kintoneレコード数上限の考え方はこちら

API制限はエラー対応ではなく設計で避ける

kintone API制限への対応を、エラー対応として考えると後手になります。

必要なのは、実装前の設計です。

設計で決めること	見る理由
対象処理	どの業務処理がAPIを呼ぶか
対象件数	1回で何件処理するか
実行頻度	何分ごと、何時間ごと、何日に1回か
並列数	同時に何本のAPI処理が走るか
差分条件	全件ではなく変更分だけ処理できるか
実行時間帯	他処理や利用者操作と重ならないか
失敗時の扱い	自動再試行、手動確認、除外を分けるか
ログ	何件成功し、何件失敗し、どこから再開するか

公式情報で見る制限は複数あります。

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

また、1日に実行できるAPIリクエスト数は契約コースによって異なり、APIリクエスト数はkintoneシステム管理のアプリ管理画面で確認でき、毎日日本時刻午前9時にリセットされると説明されています。

kintoneヘルプ：制限値一覧

cybozu developer networkのREST API共通仕様では、同時にリクエストできるAPIは1ドメインにつき100まで、1つのアプリにつき実行できるAPIリクエスト数はスタンダードコース10,000件、ワイドコース100,000件と説明されています。

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

ただし、重要なのは数値を読むことではありません。

次のように、制限を処理設計へ変換します。

公式上の制限	設計での読み替え
同時接続100	同じ時間帯に走る処理を制御する
1日あたりAPIリクエスト数	全件取得やポーリングを減らす
1回100件のレコード操作	チャンク分割と再開位置を持つ
Bulk Request最大20件	整合性を保つ単位を決める
リクエストボディ50MB	大きな更新を詰め込みすぎない
ファイル一時保存3日	ファイル処理の失敗時に放置しない

API制限を設計に落とすときは、「何回呼べるか」ではなく、「どの処理を、何件ずつ、何本並列で、いつ流すか」に変換します。

429が起きる代表パターン

429は、同時接続が集中したときに起きます。

Kintone Developer Programの記事では、1つのKintone環境に対して同時に接続できるREST APIは最大100で、100を超えるとHTTPステータスコード429が返ると説明されています。

同じ記事では、短時間に複数リクエストを送ること、Bulk Request APIのような重いAPIを使うこと、大量の読み取り・削除・アプリ更新を行うこと、カスタマイズやスクリプトが多数のREST APIを同時または短時間に発行することが、同時接続増加につながる例として挙げられています。

Kintone Developer Program：How to Avoid Kintone REST API limits

実務では、次のような処理が原因になりやすいです。

処理	起きやすい問題	対策
一括更新	100件単位の更新を多数並列で投げる	キュー化し、ワーカー数を決める
定期同期	毎回全件取得し、処理時間が伸びる	更新日時や状態で差分取得する
画面カスタマイズ	一覧表示のたびに複数APIを呼ぶ	初期表示で呼ばない、キャッシュする
帳票生成	発行時に複数アプリを取得する	帳票用データを事前作成する
添付ファイル処理	ダウンロード/アップロードが連続する	対象を絞り、処理単位を小さくする
Webhook連携	イベント発生ごとに即時更新する	受付と処理を分け、キューで流す
夜間バッチ	複数ジョブが同時刻に始まる	30分単位でずらす
再実行	失敗分をすぐ全件再試行する	バックオフし、失敗箱へ分ける

429が出たときに確認する順番は、次の通りです。

順番	確認すること
1	どのアプリ、どのAPI、どの時間帯で起きたか
2	その時間帯に他のバッチやユーザー操作が重なっていないか
3	同じ処理が並列に走っていないか
4	全件取得や全件更新になっていないか
5	リトライが短い間隔で繰り返されていないか
6	失敗した処理だけ再実行できる状態か

ここで避けたいのは、「とりあえずリトライを増やす」です。

429の直後に即時再試行すると、同時接続が下がる前にまたAPIを投げることになります。

結果として、成功率が上がるどころか、詰まりやすくなります。

同時接続数を監視する方法

制限を避けるには、同時接続数を見えるようにします。

cybozu developer networkでは、kintone.api.getConcurrencyLimit()でkintone REST APIの同時接続数の上限値と、現在の同時接続数を取得できると説明されています。

戻り値には、上限値を示すlimitと、現在の同時接続数を示すrunningが含まれます。

cybozu developer network：kintone REST API同時接続数を取得する

また、REST API共通仕様では、レスポンスヘッダーとしてX-ConcurrencyLimit-LimitとX-ConcurrencyLimit-Runningが説明されています。

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

これらは、制限に当たった後の調査だけでなく、制限に近づく前の判断に使います。

監視する値	見ること
limit	上限値。通常は100
running	現在の同時接続数
HTTPステータス	429、4xx、5xxの分類
API種別	取得、登録、更新、削除、Bulk Request
アプリID	どのアプリに集中しているか
時間帯	朝、昼、夕方、夜間に偏りがないか
処理ID	どのバッチや画面操作に紐づくか

実装側では、次のような判断を入れます。

状態	処理方針
runningが低い	通常通り処理する
runningが中程度	ワーカー数を増やさない
runningが高い	新規処理を待機させる
429が出た	即時再試行せず、待機時間を伸ばす
429が続く	対象ジョブを失敗箱へ移す

同時接続数は、障害調査のためだけでなく、処理を流すか待たせるかを判断する運用指標として扱います。

全件処理を分割する

API制限に当たりやすい処理の多くは、全件処理です。

全件取得。

全件更新。

全件削除。

全件再集計。

全件再送信。

全件は、最初の実装では分かりやすいです。

しかし、件数が増えると、時間もリクエスト数も伸びます。

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

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

このため、全件処理ではなく、処理単位を決めます。

処理	分割方法
レコード取得	更新日時、状態、レコード番号範囲で分ける
レコード更新	100件単位でチャンク化する
一括削除	対象一覧を作り、承認後に分割実行する
帳票生成	対象期間や発行単位で分ける
添付ファイル処理	レコード単位またはファイル単位で分ける
外部送信	キューに積み、順番に送る

分割処理では、再開できることが重要です。

途中で止まっても、最初から全件やり直さないようにします。

持つべき情報	目的
処理ID	1回の実行を識別する
対象条件	どの一覧、どの期間、どの状態を処理したか
チャンク番号	何番目の分割か
開始キー	どこから処理したか
終了キー	どこまで処理したか
成功件数	正常に終わった件数
失敗件数	再実行対象の件数
次回起点	再開位置

分割しても、並列数を上げすぎると意味がありません。

100件ずつ分けても、50本同時に投げれば同時接続を圧迫します。

分割は、キューとワーカー数の制御とセットで設計します。

差分同期と実行時間帯の設計

API制限を避ける基本は、全件ではなく差分です。

差分同期では、対象を絞ります。

差分条件	使いどころ
更新日時	変更されたレコードだけ拾う
作成日時	新規登録だけ拾う
ステータス	送信待ち、承認済み、確定済みだけ処理する
同期済みフラグ	外部送信済みを除外する
連携対象チェック	手動で対象を明示する
レコード番号範囲	初回移行や大量処理を範囲分割する

ただし、差分条件にも落とし穴があります。

落とし穴	対策
更新日時の境界で取りこぼす	数分重ねて取得し、処理済み判定で重複を除く
ステータス変更前に処理される	処理対象状態を明確にする
同期済みフラグだけで判断する	外部IDや処理ログでも確認する
手動チェックが押されない	一覧や通知で未処理を見えるようにする
再処理時に重複登録される	外部IDで冪等にする

実行時間帯も分けます。

kintone SIGNPOSTの性能上の考慮点では、大量データや複雑な処理では、データ量、複雑度、アクセス数が複合的に影響すると説明されています。

また、不要なデータの見直し、アプリ分割、絞り込み・ソート条件、アクセス権、デフォルト一覧の見直しなど、設計時に検討すべきことが整理されています。

kintone SIGNPOST：性能上の考慮点と改善策

API制限でも同じです。

利用者が多い時間帯に、重い処理を走らせない方がよいです。

時間帯	処理例
業務時間中	画面操作に必要な最小限のAPI
昼休み前後	軽い差分同期
終業後	当日分の集計、外部送信
夜間	大量更新、帳票用データ作成、外部DB反映
早朝	結果通知、失敗確認、再実行候補の整理

夜間に寄せるだけでも不十分です。

0時ちょうどに全ジョブを開始すると、夜間でも集中します。

15分、30分、1時間単位でずらし、同時に走るジョブ数を決めます。

Bulk Requestを使うときの注意点

Bulk Requestは、制限回避の万能策ではありません。

cybozu developer networkのBulk Request APIでは、最大で20件のリクエストを同時に処理でき、いずれかのAPIで失敗した場合、それ以降のAPIは実行されず、すべての処理がロールバックされると説明されています。

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

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

kintoneヘルプ：制限値一覧

つまり、Bulk Requestの役割は、リクエスト数を消すことではありません。

関連する更新をまとめて、整合性を保ちやすくすることです。

使い方	判断
案件とタスクをまとめて作る	向いている
在庫引当と履歴登録をまとめる	向いている
失敗時に全部戻したい処理	向いている
単純に日次リクエスト数を減らしたい	目的がずれている
重い処理を大量にまとめたい	同時接続や処理時間に注意

Bulk Requestを使う場合も、次を決めます。

設計項目	内容
まとめる単位	どこまでを同時成功にするか
失敗時の扱い	どのエラーで手動確認にするか
APIトークン	複数アプリなら各アプリのトークンを用意する
ログ	内包した各APIの結果を記録する
再実行	全体を再実行するか、再作成用の別処理にするか

Bulk Requestは便利ですが、設計なしに入れると、1つの失敗でまとまって戻る範囲が広すぎることがあります。

リトライ・バックオフ・失敗ログ

API制限に強い処理では、失敗を前提にします。

「失敗しないようにする」だけでは足りません。

失敗したときに、どこまで成功し、どこから再開すればよいかを残します。

エラー	自動再試行	手動確認
429	時間を空けて再試行	継続する場合は必要
5xx	段階的に再試行	長時間続く場合は必要
400	原則しない	データ形式や必須項目を確認
401/403	原則しない	認証、権限、IP制限を確認
レコード競合	最新revision確認後に再試行	同じレコードへの同時更新が多い場合
ファイル期限切れ	原則しない	再アップロードが必要

バックオフは、待ち時間を少しずつ伸ばします。

たとえば、1分後、5分後、15分後、60分後です。

これを無制限に繰り返してはいけません。

最大回数を超えたら、失敗箱へ移します。

失敗箱に入れる情報は、次のようにします。

項目	内容
処理ID	どの処理で失敗したか
対象アプリID	対象アプリ
レコードID	対象レコード
API種別	取得、登録、更新、削除、Bulk Request
エラーコード	kintoneから返ったコード
HTTPステータス	429、400、403など
リクエスト概要	何をしようとしたか
再実行回数	何回試したか
次回実行時刻	再試行予定
手動対応メモ	データ修正や除外理由

API制限対策では、成功処理よりも失敗処理の設計が重要です。再試行、失敗箱、手動確認、再実行ボタンまで決めておきます。

再実行ボタンも、全件再実行ではなく、失敗した対象だけにします。

再実行単位	向いている場面
レコード単位	入力値の修正後に1件だけ戻す
チャンク単位	100件更新の一部が止まった
処理ID単位	1回のバッチをまとめて再実行する
条件単位	特定期間や特定ステータスだけ再実行する

kintoneバックアップの設計方法はこちら

制限が厳しい処理を外部基盤に逃がす判断

kintone API制限に当たり続ける場合、すべてをkintone内で処理しようとしている可能性があります。

kintoneは、現場が入力し、確認し、承認し、状態を進める場として強いです。

一方で、大量ログ、横断集計、重い加工、長期保管、BI用データ作成をすべてkintone APIで都度処理すると、制限に近づきやすくなります。

kintoneに残す処理	外部基盤へ分ける処理
現場入力	大量ログ保存
担当者の確認	横断検索
承認・ステータス管理	BI用データ整形
直近の一覧	長期保管
差し戻しやコメント	複雑な集計
個別レコードの再実行	大量バッチの中間処理

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

外部基盤へ分ける場合も、kintone APIを使います。

そのため、初回全件移行と日次差分同期を分けます。

フェーズ	設計
初回移行	対象期間、対象アプリ、チャンク単位を決める
日次差分	更新日時、状態、フラグで対象を絞る
再同期	失敗期間だけ戻せるようにする
削除反映	物理削除ではなく削除フラグも検討する
権限	外部側で見せてよい範囲を再設計する
ログ	kintone取得、外部保存、失敗、再実行を残す

外部基盤へ分ける判断は、kintoneを諦めることではありません。

kintoneを現場の操作画面として使い続けるために、重い処理を分担する判断です。

実装前チェックリスト

kintone API制限を避けるために、実装前に次を確認します。

チェック	内容
制限の種類	同時接続、日次リクエスト数、100件単位、Bulk Request、ファイル処理を分けたか
処理の棚卸し	一括更新、定期同期、画面カスタマイズ、帳票、添付、Webhookを洗い出したか
件数見積もり	1回、1日、1か月の対象件数を見たか
並列数	同時に走るワーカー数を決めたか
差分条件	全件処理を避ける条件を決めたか
実行時間帯	業務時間中、夜間、早朝で処理を分けたか
同時接続監視	limitとrunningを見る方法を決めたか
429対応	即時再試行ではなくバックオフにしたか
ログ	成功、失敗、対象件数、再実行可否を残すか
再実行	失敗対象だけ戻せるか
権限	APIトークン、ユーザー権限、IP制限を確認したか
外部分担	大量ログや横断集計を外部へ分けるか

設計書には、APIのエンドポイントだけでなく、次を書きます。

設計書に書くこと	理由
処理一覧	どの処理がAPIを呼ぶかを見えるようにする
同時実行設計	429を避ける
日次API見積もり	リクエスト数超過を早めに見る
分割単位	途中停止時に再開する
バックオフルール	混雑時の再試行を抑える
失敗箱仕様	手動確認を漏らさない
再実行画面	運用者が戻せるようにする
外部基盤との分担	kintoneに重い処理を集中させない

Bitlightに相談できること

kintone API制限は、コードだけの問題ではありません。

どの業務処理がAPIを呼ぶか、どの時間帯に集中するか、どのエラーを自動で戻すか、どのエラーを人が確認するかまで含めて設計する必要があります。

Bitlightでは、既存のkintoneアプリと外部連携を見ながら、次のような支援ができます。

• APIリクエストが増えている処理の棚卸し
• 429が起きる時間帯、処理、API種別の整理
• 全件処理を差分同期や分割処理へ変える設計
• キュー、ワーカー数、実行時間帯、バックオフの設計
• 失敗ログ、失敗箱、再実行ボタンの設計
• APIトークン、IP制限、権限まわりの見直し
• kintoneに残す処理と外部基盤へ分ける処理の整理

API制限に当たってから場当たり的に直すと、業務処理のどこまで戻せばよいか分かりにくくなります。

連携処理が増えてきた段階で、制限、ログ、再実行、外部分担をまとめて設計しておく方が安全です。