レート制限
Cacoo API は各ユーザーに対して、1分間に受付可能なリクエスト数を制限します。この制限は、以下の種別ごとに適用されます。
リクエスト数は毎分0秒から1分ごとに数え、X-RateLimit-Reset の時刻にリセットします。上限を超えて拒否されたリクエストも数えます。
種別と上限
| 種別 | 1分間の上限 |
|---|---|
| 読み込み | 60 |
| 更新 | 30 |
上限はすべてのプランで共通です。
読み込み
更新
GET で呼び出した場合も、更新として数えます。
制限の対象外
以下のリクエストは、この制限の対象外です。
- ユーザ情報取得
- 図の埋め込み(oEmbed)
- 認証情報（APIキー、アクセストークン、Cacoo へのログイン状態）を伴わない、公開された図の画像の取得
- 認証・認可のエンドポイント（認証と認可を参照）
レスポンス
ステータスライン
リクエスト数が上限を超えた場合、APIサーバは429（Too Many Requests）を返します。レスポンスボディは、エンドポイントやレスポンス形式（.json / .xml / 画像）にかかわらず以下の JSON です。
{
"error": {
"code": "rate_limited",
"message": "Too many read calls. Retry after 12 seconds."
}
}
レスポンスヘッダ
制限の対象となるリクエストのレスポンスには、以下のヘッダが含まれます。ただし、エラーレスポンスや、一時的に計測できない場合には含まれないことがあります。ヘッダが無い場合は、残り回数が不明として扱ってください。
| HTTPヘッダ名 | HTTPヘッダの内容 |
|---|---|
| X-RateLimit-Limit | 1分間に受付可能な最大リクエスト数 |
| X-RateLimit-Remaining | X-RateLimit-Resetの時刻までに受付可能な残りリクエスト数 |
| X-RateLimit-Reset | リクエスト数の計測がリセットされる時刻（UNIX時間） |
| X-RateLimit-Used | 現在の1分間に受け付けたリクエスト数（今回を含む） |
429 を返すときは、さらに以下のヘッダが含まれます。
| HTTPヘッダ名 | HTTPヘッダの内容 |
|---|---|
| Retry-After | 次のリクエストを送信できるまでの秒数 |
レスポンスヘッダ例
2026年11月16日9:00:00(JST)からの1分間に、読み込みのリクエストを8回実行した場合のレスポンスヘッダの例です。残り52回のリクエストが可能で、2026年11月16日9:01:00（JST/UNIXタイムスタンプ1794787260）にリクエスト数がリセットされることを示しています。
- X-RateLimit-Limit: 60
- X-RateLimit-Remaining: 52
- X-RateLimit-Reset: 1794787260
- X-RateLimit-Used: 8
レート制限への対策
レート制限に抵触しないために、以下の対策を行ってください。
- 1つのソフトウェアから、同時に複数のリクエストを送信しない。1つのリクエストに対して応答が返されてから、次のリクエストを送信する。
- 多数の図を続けて取得・更新する場合は、X-RateLimit-Remaining を確認し、残りが少なくなったら X-RateLimit-Reset の時刻まで待つ。
- 429 が返された場合は、Retry-After の秒数が経過してからリクエストを再送する。
- 定期的に実行するソフトウェア（定時バッチなど）の場合、過去のリクエスト結果をキャッシュし、なるべくリクエスト数を減らす。
一方、このレート制限を回避するために、 1つのソフトウェアが、複数のユーザーのAPIキーを用いてリクエストを送信することは推奨しません。
注意点
この制限は APIキーやアプリケーション単位ではなく、ユーザー単位であることにご注意ください。
認証方法（APIキー、OAuth のアプリケーション、Cacoo にログイン中のブラウザ）を問わず、同じユーザーのリクエストは同じ上限を共有します。ある APIキーが制限を受けている時間には、同じユーザーのほかの APIキーやアプリケーションも同じ制限を受けます。
ヌーラボが提供する連携（Google ドキュメントのアドオンなど）のリクエストも、同じ上限に数えます。