結論: API 連携の事故は、 冪等性・rate limit・整合性回復・監査ログの 4 軸を設計段階で言語化していないことに収束します。 動かしてから直す順序では、 直すコストが大きくなりがちです。
API 連携で繰り返される 4 つの落とし穴
AI と会計・労務・顧客管理などの既存システムを API で繋ぐ取り組みは、 士業事務所でも段階的に広がってきています。 一方で、 「テスト環境では問題なく動いていたバッチが、 本番投入後の数週間で想定外の挙動を起こした」 という事象が、 周辺で繰り返し観察されます。 たとえば、 メール配信 API がたまたまタイムアウトを返したことをきっかけに再送ロジックが過剰に動き、 顧問先全員に同じレポートが複数回送られてしまう、 というケースがあります。
筆者の観測の範囲では、 こうした事案は次の 4 つの落とし穴に収束する傾向があります。
- 二重実行・多重送信 ——「失敗したかもしれないから、 もう一回」 を機械的に繰り返した結果、 同じ仕訳・同じメール・同じ請求書が複数件作られてしまうケースです
- 静かな失敗 ——API が
200 OKだが本文にエラーが入っている、 あるいは5xxを返したのに上流が握り潰している。 気付いたときには数百件が未連携、 ということがあります - rate limit による全停止 ——ある時間帯だけ集中処理した結果、 API 側の流量制限に引っかかり、 その日の連携が丸ごと止まってしまうケースです
- データ整合性の崩れ ——片方のシステムには登録され、 もう片方には登録されていない「半分入った」 状態のレコードが残ってしまうことがあります
これらは独立した事故ではなく、 設計時に 4 軸を分けて考えていないことで複合的に発生します。 以下、 軸ごとに設計のポイントを整理していきます。
冪等性と rate limit の設計
冪等性 (idempotency) とは、 「同じ操作を 1 回やっても 100 回やっても、 結果が変わらない」 という性質を指します。 HTTP の PUT や DELETE は冪等であることが期待される、 と一般的に整理されています。 一方で、 API 連携で事故りやすい事務所の多くは、 POST を冪等でないまま運用している点に気付いていません。
設計時に決めておきたいのは以下の 3 点です。
- idempotency key の発行: クライアント側でリクエスト 1 件ごとに一意の ID を採番し、 API 側でそれを重複検知に使います。 主要な決済系 SaaS では
Idempotency-Keyヘッダで明示的にサポートされています - 「再送して安全な処理」 と「再送禁止な処理」 を分ける: 請求書発行・メール送信のような外部副作用を伴う処理は、 冪等性なしに再送ロジックを組むと事故の温床になります
- 失敗時のリトライ前に状態確認 API を叩く: タイムアウト時に、 サーバ側で「成功している可能性」 を確認するエンドポイントを設けると、 二重実行の多くは回避できます
冒頭の「同じレポートが何通も送られる事案」 は、 idempotency key を持たずにタイムアウト → リトライを機械的に組んだことが直接の原因と推測できます。
rate limit は、 ほとんどの業務 SaaS API に設定されています (1 秒あたり / 1 分あたり / 1 時間あたりのリクエスト数制限)。 これを軽視した連携は、 「ある日突然動かなくなる」 構造を抱えやすくなります。 公開されているセキュリティガイドラインでも、 「リソース消費の制限不足は、 サービス停止や運用コスト増加を引き起こす可能性がある」 と整理されています。 これは API 提供側の話ではありますが、 利用側にとっても同じ構造です。 制限を考慮しない連携設計は、 自社のバッチを自分で止めることに繋がってしまいます。
設計の勘所は次のとおりです。
- 公式ドキュメントで rate limit の数値を確認する ——「だいたい大丈夫だろう」 ではなく、 必ず実数を読みます
- 指数バックオフ (exponential backoff) を入れる ——429 が返ったら 1 秒・2 秒・4 秒……と待ち時間を伸ばします。 即座に再送し続けると、 永久に解除されないことがあります
- ピーク時間をずらす ——月末・四半期末・年度末に集中するバッチは、 時間帯を分散する設計が望ましいです
- キュー (queue) を挟む ——直接 API を叩くのではなく、 一度キューに積んで一定レートで流す構造にすると、 rate limit に当たりにくくなる傾向があります
データ整合性と監査ログ
複数の API を順に呼ぶ処理 ——たとえば「会計に仕訳を作って、 顧客管理に履歴を残して、 チャットツールに通知する」 ——では、 途中で 1 つだけ失敗するケースが必ず起き得ます。 データベース内で完結する処理なら ROLLBACK で済みますが、 外部 API はそうはいきません。 「会計だけ登録されて、 顧客管理には残っていない」 という半端な状態をどう扱うか、 設計時に決めておく必要があります。
現実的な選択肢は次の 3 つです。
- 補償トランザクション (compensating transaction): 後続で失敗したら、 前のステップを「打ち消す」 API を呼びます。 仕訳の取消、 通知の取り消しメール、 などが典型例です
- イベントログを残して人間が確認する: 完全自動で整合性を取らず、 「整合性違反」 をログに出して人間がチェックする運用にします。 中小事務所ではむしろこちらが現実的です
- 「再実行可能」 な設計にする: 全ステップが冪等であれば、 失敗した時点から最後まで再実行するだけで整合性が戻る、 という設計も可能です
完全自動の sagas パターンを士業事務所が内製するのは負荷が高いため、 「失敗したら止めて人間に通知する」 運用設計を出発点にするのが堅実だと考えています。
加えて、 連携経路全体で監査ログを残すことの重要性も書いておきたいところです。 公開されている API セキュリティのガイドラインは、 認証の不備や第三者 API の不適切な利用など、 士業事務所の AI 連携に直接刺さる項目を並べています。 また、 個人情報保護を所管する公的機関からも、 生成AIサービス利用に関する注意喚起が出されており、 要配慮個人情報を含むデータを安易に外部サービスへ送信することのリスクに言及されています。 API 連携を通じて生成AIへデータを流す設計は、 こうした注意喚起の射程に入る可能性があり、 監査ログ・マスキング・暗号化・データ越境の論点を設計初期に置いておく必要があります。 公式情報を確認のうえ、 自所の運用に当てはめておきたいところです。
最低限決めておきたい項目は次のあたりに集約されます。
- 認証方式: OAuth 2.0 / API Key / JWT のどれを使うか、 トークンの保管場所はどこか
- 秘密情報の管理: API キーを Git にコミットしていないか、
.envの管理者は誰か - 通信の暗号化: HTTPS 必須です。 社内 LAN 内であっても、 業務システム間は TLS を張る運用が望ましいです
- 監査ログ: どの API を、 誰が、 いつ、 どのデータに対して呼んだか、 を遡れる状態にしておきます
- 個人情報のマスキング: AI に渡す前に氏名・住所・マイナンバーを置換する前処理を入れるかどうかを決めます
- データ越境: 海外リージョンの API に顧客情報を送るときは、 顧問先との契約・個情法を確認します
教訓
冒頭の「同じレポートが何通も送られる事案」 から取り出せる教訓を、 4 つに絞って残しておきたいと思います。
1. リトライ設計より先に、 冪等性設計 リトライは「失敗したら再送する」 だけの単純なロジックに見えますが、 冪等性が担保されていない処理にリトライを足すと事故の増幅器になってしまいます。 順序として、 冪等性の設計が先で、 リトライはその上に乗せるかたちが望ましいです。
2. 「動いている」 と「監視されている」 は別 本番投入後しばらくは何も起きないことが多いため、 監視を後回しにしがちです。 一方で、 事故は監視がない時に起きます。 連携を本番に乗せる時点で、 失敗が人間に通知される経路を併走させたいところです。
3. 「夜中に走らせる」 設計は、 朝に確認できる前提で組む バッチを深夜帯に動かすこと自体は理にかなっていますが、 朝までに何が起きたかが分かる状態になっていないと、 検知が半日遅れてしまいます。 朝一でログを確認する運用ルーティンと、 異常時の通知経路を併せて設計しておきたいところです。
4. 設計レビューは「動くこと」 ではなく「壊れたときの挙動」 を見る 動作確認は「成功ケース」 を見るので通ってしまいます。 設計レビューは「タイムアウトしたとき」「429 が返ったとき」「片方の API だけ失敗したとき」 の挙動を見る作業として、 別の時間で組むのが現実的です。
API 連携は「動いた / 動かない」 の二択ではなく、 冪等性・rate limit・整合性回復・監査ログが設計に組み込まれているかで本番運用の質が決まる、 と整理しておきたい場面です。
参考
- HTTP メソッドの冪等性に関する公開ドキュメント (公式情報を確認のこと)
- API セキュリティに関する公開ガイドライン (公式情報を確認のこと)
- 個人情報保護を所管する公的機関による生成AIサービス利用に関する注意喚起 (公式情報を確認のこと)