もしあなたがZendeskとの連携機能を構築している場合、午前2時に「429 Too Many Requests（リクエストが多すぎます）」エラーが発生するのは楽しくありません。コーディングを始める前にZendesk APIのレート制限を理解しておくと、必死のデバッグ作業や、チケットの同期が停止した理由を尋ねる怒った関係者からの問い合わせから解放されます。
このガイドでは、Zendesk APIのレート制限について知っておくべきことをすべて解説します。プランごとの段階的な制限、リアルタイムでの使用状況の監視方法、レート制限エラーを適切に処理するための実践的な戦略について説明します。チケットデータの同期、カスタムダッシュボードの構築、ワークフローの自動化など、信頼性の高いパフォーマンスを提供しながら制限内に収まる連携機能を構築する方法を学びます。
レート制限に一切対処したくないチームのために、別の方法もあります。ZendeskのためのeeselのAIエージェントは、Zendeskに直接接続し、レート制限を自動的に処理します。両方のアプローチを検討して、チームに合ったものを選択できるようにします。
Zendeskの段階的なレート制限について
Zendeskは、プランの種類と使用している特定のAPIエンドポイントに応じて、異なるレート制限を適用します。知っておくべきことを詳しく見ていきましょう。
プラン層別のレート制限
SupportおよびHelp Center APIのレート制限は、Zendeskのプランによって大きく異なります。
| プラン | 1分あたりのリクエスト数 |
|---|---|
| Team | 200 |
| Growth | 400 |
| Professional | 400 |
| Enterprise | 700 |
| Enterprise Plus | 2500 |
| High Volume APIアドオン | 2500 |
High Volume APIアドオンを使用すると、制限が1分あたり2500リクエストに増加します。Zendesk Suite Growthプラン以上、およびZendesk Support Professionalプラン以上で利用できます。このアドオンを購入するには、最低10席のエージェントシートが必要です。Enterprise Plusプランには、このアドオンがデフォルトで含まれています。
エンドポイント固有の制限
一部のエンドポイントには、アカウント全体の制限を上書きする独自レート制限があります。
| エンドポイント | レート制限 |
|---|---|
| 増分エクスポート | 1分あたり10リクエスト |
| チケット一覧（500ページ超） | 1分あたり50リクエスト |
| チケットの更新 | ユーザーごと、チケットごとに10分あたり30件の更新 |
| Chat API | 1分あたり200リクエスト（すべてのプラン） |
大規模なデータセットを同期している場合、増分エクスポートのエンドポイントは特に重要です。これらのエンドポイントへのリクエストは1分あたり10件しか実行できませんが、High Volume APIアドオンがある場合は1分あたり30件に増加します。
Help Center APIに関する考慮事項
Help Center APIは、Support APIと同じレート制限を使用します。ただし、Help Center APIへのリクエストはSupport APIのレート制限にはカウントされず、その逆も同様です。つまり、Enterpriseプランでは、Support APIに700件のリクエストを行い、同時にHelp Center APIに別の700件のリクエストを行うことができます。
コード内でZendesk APIの1分あたりのリクエスト数レート制限を監視する
Zendeskは、リアルタイムでレート制限のステータスを監視できるレスポンスヘッダーを提供します。これは、リクエストレートを動的に調整できる連携機能を構築するために不可欠です。
レスポンスヘッダーについて
ZendeskからのすべてのAPIレスポンスには、現在のレート制限ステータスを示すヘッダーが含まれています。
- X-Rate-Limit または ratelimit-limit：アカウントの現在のレート制限（例：700）
- X-Rate-Limit-Remaining または ratelimit-remaining：現在の1分間に残っているリクエスト数
- ratelimit-reset：現在のレート制限ウィンドウがリセットされるUnixタイムスタンプ
- zendesk-ratelimit-tickets-index：チケット一覧エンドポイントの追加制限情報
チケット一覧またはユーザー検索などのTicketing API一覧エンドポイントの場合、追加のヘッダーが表示されます。
x-rate-limit: 700
ratelimit-limit: 700
x-rate-limit-remaining: 699
ratelimit-remaining: 699
ratelimit-reset: 41
zendesk-ratelimit-tickets-index: total=100; remaining=99; resets=41
出典：レート制限を回避するためのZendeskベストプラクティス
Pythonでヘッダーを読み取る
Pythonでレート制限ヘッダーを抽出して使用する方法を次に示します。
import requests
import time
def call_zendesk_api():
url = "https://subdomain.zendesk.com/api/v2/tickets"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
response = requests.get(url, headers=headers)
should_continue = handle_rate_limits(response)
if should_continue:
# Process the API response
pass
def handle_rate_limits(response):
account_limit = response.headers.get("ratelimit-remaining")
endpoint_limit = response.headers.get("Zendesk-RateLimit-Endpoint")
account_limit_reset = response.headers.get("ratelimit-reset")
if account_limit:
account_remaining = int(account_limit)
if account_remaining > 0:
if endpoint_limit:
endpoint_remaining = int(endpoint_limit.split(";")[1].split("=")[1])
if endpoint_remaining > 0:
return True
else:
endpoint_reset = int(endpoint_limit.split(";")[2].split("=")[1])
handle_limit_exceeded(endpoint_reset)
else:
return True
else:
handle_limit_exceeded(account_limit_reset)
return False
def handle_limit_exceeded(reset_time):
wait_time = int(reset_time) - int(time.time()) + 1
print(f"Rate limit exceeded. Waiting {wait_time} seconds...")
time.sleep(wait_time)
JavaScriptでヘッダーを読み取る
async/awaitを使用したJavaScriptでの同じロジックを次に示します。
const axios = require('axios');
async function callZendeskAPI() {
const url = "https://subdomain.zendesk.com/api/v2/tickets";
const headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"};
try {
const response = await axios.get(url, { headers });
const shouldContinue = handleRateLimits(response);
if (shouldContinue) {
// Process the API response
}
} catch (error) {
console.error(error);
}
}
function handleRateLimits(response) {
const accountLimit = response.headers["ratelimit-remaining"];
const endpointLimit = response.headers["Zendesk-RateLimit-endpoint"];
const accountLimitReset = response.headers["ratelimit-reset"];
if (accountLimit) {
const accountRemaining = parseInt(accountLimit);
if (accountRemaining > 0) {
if (endpointLimit) {
const endpointRemaining = parseInt(endpointLimit.split(";")[1].split("=")[1]);
if (endpointRemaining > 0) {
return true;
} else {
const endpointReset = parseInt(endpointLimit.split(";")[2].split("=")[1]);
handleLimitExceeded(endpointReset);
}
} else {
return true;
}
} else {
handleLimitExceeded(accountLimitReset);
}
}
return false;
}
async function handleLimitExceeded(resetTime) {
const waitTime = (resetTime || 60) - Math.floor(Date.now() / 1000) + 1;
console.log(`Rate limit exceeded. Waiting ${waitTime} seconds...`);
await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
}
429 Too Many Requestsエラーの処理
Zendesk APIの1分あたりのリクエスト数レート制限を超過すると、APIは429ステータスコードを返します。このレスポンスをどのように処理するかによって、連携機能が適切に失敗するか、完全に壊れるかが決まります。堅牢な連携機能を構築するための詳細については、Zendeskに最適なAIチャットボットに関するガイドをご覧ください。
429エラーの意味
429 Too Many Requestsレスポンスは、レート制限に達したことを示します。レスポンスには、再試行するまでに待機する秒数を示すRetry-Afterヘッダーが含まれています。
HTTP/1.1 429
Status: 429
Retry-After: 93
この例では、別のリクエストを行う前に93秒待つ必要があります。このヘッダーを無視してリクエストを続行すると、デバッグが困難になるnullエラーが発生する可能性があります。
指数バックオフの実装
本番環境の連携機能では、指数バックオフを実装してレート制限を適切に処理します。
import time
import random
def make_request_with_backoff(url, headers, max_retries=5):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 200:
return response
elif response.status_code == 429:
retry_after = int(response.headers.get('Retry-After', 60))
# Exponential backoff with jitter
wait_time = retry_after * (2 ** attempt) + random.uniform(0, 1)
print(f"Rate limited. Waiting {wait_time:.1f} seconds...")
time.sleep(wait_time)
else:
response.raise_for_status()
raise Exception("Max retries exceeded")
指数バックオフアプローチは、再試行間の待機時間を増やし、サーバーに過負荷をかける可能性を減らしながら、リクエストが成功する可能性を高めます。
エラー処理のベストプラクティス
本番環境でレート制限を処理するための主要なプラクティスを次に示します。
- 429エラーを無視しないでください。 制限に達した後もリクエストを続行すると、連携機能が役に立たないnullエラーで失敗する可能性があります。
- 常にRetry-Afterヘッダーを解析します。 これにより、待機する正確な時間がわかります。
- 高トラフィックアプリケーションにはサーキットブレーカーパターンを実装します。 レート制限に一貫して達する場合は、すぐに再試行するのではなく、一時的にリクエストを一時停止します。
- レート制限イベントをログに記録します。 いつ、なぜ制限に達したかを追跡して、最適化の機会を特定します。
- グレースフルデグラデーションを設計します。 APIリクエストが遅延した場合でも、アプリケーションは引き続き機能する必要があります。
ZendeskでのAPI使用状況の監視
コード内のヘッダーの監視に加えて、ZendeskはAPIの使用状況を長期的に追跡するためのツールを提供します。
管理センターダッシュボードの使用
Zendesk管理センターでAPIの使用状況を表示できます。
- 管理センター > アカウント > 使用状況 > API に移動します。
- レート制限に対する使用状況を示す7日間の概要を表示します。
- 過去7日間の429エラーの割合を確認します。
- 制限に近づいた回数（容量の90〜99％）を確認します。
ダッシュボードには、APIリクエストが時間の経過とともに表示され、発信者とエンドポイントごとの合計リクエストの内訳が表で示されます。コンテンツは毎日更新されますが、現在の使用状況が表示されるまでに最大72時間かかる場合があります。
注：API使用状況ダッシュボードは、1分あたり2500を超えるリクエストを使用するアカウント、またはSupportが含まれていないスタンドアロンアカウントでは使用できません。
API使用状況通知
Zendeskは、レート制限に近づくと通知を提供します。
- 違反寸前警告： API呼び出しがプラン制限の90〜99％の間で測定された場合に警告します。
- 429エラー追跡： レート制限エラーを返すリクエストの割合を監視します。
- 毎日の概要： 過去7日間の傾向を追跡します。
定期的な監視は、制限に達して運用に影響を与える前に、パターンを特定し、容量の増加を計画するのに役立ちます。
API連携の最適化
スマートな連携設計により、機能を犠牲にすることなくAPIの使用量を削減できます。Zendesk APIの1分あたりのリクエスト数レート制限内に収まるための実績のある戦略を次に示します。AI搭載のサポートツールについてさらに詳しく知りたい場合は、Zendesk AIレビューをご覧ください。
リクエストのバッチ処理
チケットごとに個別のAPI呼び出しを行う代わりに、バッチエンドポイントを使用します。
- show_manyエンドポイント： 1つのリクエストで複数のチケット、ユーザー、または組織を取得します。
- サイドローディング：
includeパラメーターを使用して、関連データ（チケットのコメントなど）を1回の呼び出しで取得します。 - 一括更新： 可能な場合は、1つのリクエストで複数のチケットを更新します。
バッチ処理により、ユースケースに応じてAPI呼び出し量を50〜90％削減できます。
キャッシュの実装
頻繁に変更されないデータをキャッシュします。
- ユーザーおよび組織データ： 変更頻度が少ないため、数時間または数日間キャッシュします。
- チケットメタデータ： チケットフィールド、タグ、およびカスタムフィールド定義をキャッシュします。
- ヘルプセンター記事： 適切なキャッシュヘッダーを使用して記事コンテンツをキャッシュします。
Zendesk Webhookを使用してキャッシュの無効化を実装し、変更が発生したときにキャッシュされたデータをクリアして、過剰なポーリングなしで連携機能が最新の状態を維持できるようにします。
ポーリングの代わりにWebhookを使用する
変更のためにAPIをポーリングするのは非効率的であり、レート制限をすぐに消費します。Zendesk Webhookは、イベントが発生したときにシステムに通知します。
- チケットイベント： チケットが作成、更新、または解決されたときに通知を受け取ります。
- ユーザーの変更： ユーザープロファイルが変更されたときに更新を受信します。
- 組織の更新： 組織のメンバーシップの変更を追跡します。
Webhookは、継続的なポーリングの必要性を排除し、リアルタイムの更新を提供しながらAPIの使用量を大幅に削減します。
大規模なデータセットの増分エクスポート
大量のデータを同期する場合は、増分エクスポートAPIを使用します。
- 最後の同期以降に変更されたアイテムのみをリクエストします。
- 効率的な大規模データセット処理のために、カーソルベースのページネーションを使用します。
- 1分あたり10リクエストの制限内に収まります（High Volumeアドオンでは30）。
このアプローチは、特にチケット量が多いアカウントの場合、すべてのチケットを繰り返し取得するよりもはるかに効率的です。
High Volume APIにアップグレードするタイミング
最適化だけでは不十分な場合があります。High Volume APIアドオンが必要かどうかを判断する方法を次に示します。Zendeskの機能の完全な概要については、Zendeskレビューをお読みください。
アドオンが必要な兆候
次の場合は、アップグレードを検討してください。
- Enterpriseプランで1分あたり700リクエストに一貫して達している。
- ビジネスオペレーションに影響を与える連携の遅延。
- 現在の制限を超えるチケット量の増加。
- 同じレート制限プールを競合する複数の連携。
- 最適化の努力にもかかわらず、頻繁に429エラーが発生する。
価格と要件
High Volume APIアドオン：
- 制限を1分あたり2500リクエストに増やします。
- Zendesk Suite Growth +およびSupport Professional +プランで利用可能。
- 最低10席のエージェントシートが必要です。
- Enterprise Plusプランには追加費用なしで含まれています。
アップグレードする前に、現在のAPI使用状況を監査します。多くのチームは、追加費用なしでレート制限の問題を最適化できることに気付きます。
代替案：eesel AIにレート制限を処理させる
レート制限に準拠した連携機能を構築および維持するには、多大なエンジニアリング作業が必要です。APIクォータの管理よりもコア製品に集中したい場合は、別の方法があります。
eesel AIは、Zendeskに直接接続し、レート制限を自動的に処理します。当社のシステム：
- リアルタイムでレート制限ヘッダーを監視します。
- インテリジェントなリクエストキューイングとバックオフを実装します。
- 最適化されたバッチ処理を使用して、API呼び出しを最小限に抑えます。
- ポーリングの代わりにWebhookベースの更新を提供します。
- チケット量が増加するにつれてシームレスに拡張します。
429エラーと指数バックオフを処理するためのカスタムコードを作成する代わりに、自動化をわかりやすい英語で構成します。連携機能が確実に実行されるように、Zendeskのレート制限内に収まるという技術的な複雑さを処理します。Zendesk AIエージェントの機能の詳細をご覧ください。
カスタム連携機能を構築するチーム向けに、Zendesk自動化APIリファレンスで追加の技術ガイダンスを提供しています。
今すぐ信頼性の高いZendesk連携の構築を開始する
Zendesk APIのレート制限を理解することは、あらゆる連携プロジェクトに不可欠です。重要なポイントは次のとおりです。
- プランの制限を把握する：階層に応じて1分あたり200〜2500リクエスト。
- レート制限ヘッダーを監視して、リアルタイムで使用状況を追跡します。
- 429エラーの指数バックオフを実装します。
- 管理センターダッシュボードを使用して、使用パターンを追跡します。
- バッチ処理、キャッシュ、およびWebhookで最適化します。
- 最適化だけでは不十分な場合は、High Volume APIアドオンを検討してください。
カスタム連携機能を構築する場合でも、マネージドソリューションを探している場合でも、レート制限を適切に処理することで、Zendeskワークフローが中断することなくスムーズに実行されるようになります。
レート制限を気にせずにZendeskワークフローを自動化する準備はできましたか？eesel AIをお試しください。APIの複雑さを当社に任せて、優れた顧客体験の提供に集中してください。
