Airtable APIの429は、短時間の要求集中と、workspaceの月間call枠を分けて調べます。自分のscriptをゆっくりにしても、同じbaseを使う他の連携や、別workspaceの月間枠が原因なら解消しない場合があります。最初に実際のbaseと、そのbaseが属するworkspaceを確定してください。
本稿は既存API連携の診断・再開設計を扱います。AirtableへのAPI要求、制限到達試験、プラン変更、token作成は実施していません。要求数や時刻の例は架空で、契約中の環境や製品の成功実測ではありません。
目次
429を返した要求を一つ特定する
HTTPステータス、error body、時刻、endpoint、base ID、処理ID、試行回数を記録します。token自体や顧客レコードの全文は不要です。timeout、401、403、422と429を混ぜず、失敗した要求が読取か書込かも区別します。
表は横にスクロールできます
| 診断に必要な項目 | 調べる理由 | 取り違えの例 |
|---|---|---|
| 実際のbase ID | 制限される対象を固定 | 同名の別baseを見る |
| 所属workspace | 月間枠の管理単位を確認 | 自分のhome側だけ見る |
| 要求を出す連携 | 他workerと合算して考える | 自作scriptだけを計測 |
| SDK・connector・独自再試行 | 実際の試行回数を知る | 初回1回だけと数える |
| methodと対象ID | 再実行の副作用を判断 | 作成と読取を同じ扱い |
画面に表示されたworkspaceの使用量が少なくても、APIが別workspace内のbaseへ接続していれば、その値で月間枠を否定できません。まずendpointと管理画面の対象を照合します。
速度制限は、共有する単位で見る
Airtable公式のAPI call制限資料（新しいタブで開く）は、baseごとに毎秒5要求、同じuserまたはservice accountのpersonal access tokenを使う通信全体に毎秒50要求の制限を説明しています。tokenを増やせば別の独立枠になる、という設計にはしません。
架空例として、同じbaseにscriptが毎秒3要求、別の同期が毎秒3要求を出している場合、各scriptだけを見れば5未満でも合計は6です。SDK 再試行、監視の読取、Makeなど第三者連携も含め、同じ対象へ送る量を調べます。平均が低くても、一斉起動した瞬間の要求数を見落とさないようにします。
同資料は、速度超過の429後は30秒待つ必要があると案内しています。失敗したworkerだけを止め、他workerが要求を出し続ける設計では、待ったつもりでも集中が解けません。baseや認証主体ごとのqueue・抑制状態を共有できるか確認します。
月間枠は、待機とは別の問題として確認する
短時間の要求を抑えても429が続く場合は、対象workspaceのプランと当月Public API callsを、閲覧できる管理者の画面で照合します。利用量の詳細表示はプランや権限で異なるため、表示されていない分析値を推測で埋めません。metadata/schema照会や第三者connectorによる要求も、呼出量の見直しに含めます。
公式HelpはFreeとTeamに月間枠があり、超過後の扱いをそれぞれ説明しています。本文のプラン別説明とFAQの一般的な遮断説明に差があるため、本稿では「月間超過なら全プランが一律に完全停止」とは断定しません。現在の契約表示、対象workspace、応答、必要ならsupport確認を揃えます。
表は横にスクロールできます
| 観測する状態 | 主な調査方向 | 避ける判断 |
|---|---|---|
| 特定時刻に集中して429 | 同時起動・共有baseの送信量 | 月間枠だけが原因 |
| 静かな状態でも429が続く | 対象workspaceの利用量・プラン | 待機秒数だけを延ばす |
| 一つのbaseだけ止まる | baseと他連携の処理量 | token全体が壊れた |
| usageの対象とbaseが不一致 | 所属workspaceを再照合 | usageが少ないので月間枠ではない |
月間枠が原因と確認できたら、不要な呼出を抑え、resetまでの運用や契約上の選択肢を担当者が判断します。診断を理由にプランを無断で上げたり、別accountへ処理を移して制限を迂回したりしません。
SDKとアプリの再試行を二重にしない
公式JavaScript clientには制限時のbackoff・再試行処理が案内されています。利用しているSDK版やconnectorの仕様を確認し、その上に独自の無制限再試行を重ねないようにします。外から見える1回の処理が、内部で何回のHTTP要求になったかを追える記録を残します。
待機後の再開も、すべてのworkerを同時に解放しないよう調整します。回数上限と失敗通知を決め、長時間の429を成功や空結果へ変換しません。認証エラーなら認証、payload不備なら入力の修正へ分け、すべてを待機で直そうとしないことも必要です。
再開位置と書込結果を保全する
ページ取得中なら、完了したページと次のoffsetを同じ処理状態として保持します。失敗ページを0件として全件取得を終えず、復旧後は同じ条件で続け、保存済みrecord IDとの重複を確認します。読取が全件終わる前に、その結果で既存データを全置換しないようにします。
書込では、明確な429応答と、通信切断やtimeoutで結果を失った場合を分けます。後者は保存済みの可能性があるため、業務上の識別子で現在状態を確認し、同じ作成を盲目的に繰り返しません。batchを使う場合も、endpointごとの件数条件と結果を確認し、batch化だけで重複や一括原子性が保証されるとは考えません。
呼出量を減らしても必要な結果を失わない
毎回すべてのレコードを読み直す、変更していない値まで書き直す、同じschemaを何度も確認する処理を洗い出します。cache、必要な範囲の取得、適切なbatch化を検討し、必要な更新まで省いていないかを確かめます。頻度を下げる場合は、利用側に許されるデータの古さを先に決めます。
許可された検証では、mockの429と複数workerで、待機中の新規要求が抑えられるか、上限で終了するか、再開で重複が生じないかを確認します。実baseへ負荷をかけて制限値を測る必要はありません。復旧記録には、制限の単位、確認したusage、実要求数、処理の再開位置、未確認のプラン条件を残します。