Zendesk API を使用するということは、エラーコードに対処することを意味します。エラーに遭遇するかどうかではなく、いつ遭遇するかの問題です。カスタム連携を構築する場合でも、チケットワークフローを自動化する場合でも、システム間でデータを同期する場合でも、これらのエラーコードを理解することで、デバッグ時間を大幅に節約できます。
このガイドでは、Zendesk API のエラーコードについて知っておくべきことをすべて網羅しています。HTTP ステータスコード、認証エラー、レート制限、さらにはメール配信ステータスコードについて説明します。最後まで読めば、何か問題が発生したときにいつでも参照できる実用的なリファレンスになるでしょう。
API の複雑さを全体的に軽減したい場合は、eesel AI のようなツールを使用すると、チケット操作をインテリジェントに処理できるため、トラブルシューティングが必要なエラーを最小限に抑えることができます。eesel AI は、Zendesk の AI エージェント として機能し、過去のチケットやヘルプセンターから学習して、顧客の問題を自律的に解決します。
Zendesk API のエラーコードと HTTP ステータスコードについて
Zendesk API は、標準の HTTP ステータスコードを使用して、成功と失敗を伝えます。これらは、おなじみの範囲に分類されます。
- 2xx (成功): リクエストは期待どおりに機能しました
- 3xx (リダイレクト): リソースが移動したか、変更されていません
- 4xx (クライアントエラー): リクエストに問題があります
- 5xx (サーバーエラー): Zendesk 側で問題が発生しました
よく遭遇する最も一般的なコードのクイックリファレンスを次に示します。
| ステータスコード | 意味 | 一般的な原因 |
|---|---|---|
| 200 | OK | 成功した GET または PUT リクエスト |
| 201 | 作成済み | リソースを作成した成功した POST |
| 204 | コンテンツなし | 成功した DELETE リクエスト |
| 400 | 不正なリクエスト | 不正な形式のリクエストまたは必須フィールドの欠落 |
| 401 | 認証されていません | 認証に失敗しました |
| 403 | 禁止されています | 認証済みですが、権限がありません |
| 404 | 見つかりません | リソースが存在しません |
| 409 | 競合 | 同時変更または重複リクエスト |
| 422 | 処理できないエンティティ | 有効な JSON ですが、セマンティックエラーがあります |
| 429 | リクエストが多すぎます | レート制限を超えました |
| 500 | 内部サーバーエラー | Zendesk サーバーの問題 |
| 503 | サービス利用不可 | メンテナンスまたは一時的な停止 |
エラーが発生すると、Zendesk は詳細を含む JSON レスポンスを返します。一般的なエラー形式を次に示します。
{
"error": "RecordInvalid",
"description": "レコード検証エラー",
"details": {
"value": [
{
"type": "blank",
"description": "空白にすることはできません"
}
]
}
}
Sell API (Zendesk のセールス CRM) は、errors 配列と、HTTP ステータスとリクエスト ID を含む meta オブジェクトを使用して、わずかに異なる形式を使用します。
認証と認可のエラー：401 と 403
401 エラーと 403 エラーは、Zendesk API を初めて使用する開発者にとって最も混乱を招きます。どちらもアクセス制御に関連していますが、異なる段階で失敗します。
401 認証されていません：認証に失敗しました
401 エラー は、Zendesk がリクエストを認証できなかったことを意味します。誰であるかを認識できないため、権限を確認できません。
一般的な原因は次のとおりです。
- Authorization ヘッダーがないか、形式が正しくありません
- 基本認証の Base64 エンコードが正しくありません
- API トークンを使用する場合に
/tokenサフィックスを忘れている - トークンが期限切れまたは取り消された
- 基本認証ヘッダーで OAuth トークンを使用している
API トークン認証の正しい形式を次に示します。
curl -v \
-u "agent@example.com/token:YOUR_API_TOKEN" \
"https://your_subdomain.zendesk.com/api/v2/tickets.json"
Node.js では次のようになります。
import fetch from "node-fetch";
import btoa from "btoa";
const subdomain = "your_subdomain";
const email = "agent@example.com";
const token = process.env.API_TOKEN;
const response = await fetch(
`https://${subdomain}.zendesk.com/api/v2/users/me.json`,
{
headers: {
'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
'Content-Type': 'application/json'
}
}
);
OAuth の場合は、Bearer スキームを使用します。
curl \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
"https://your_subdomain.zendesk.com/api/v2/users/me.json"
403 禁止されています：認証済みですが、承認されていません
403 エラー は、Zendesk が誰であるかを認識しているが、実行しようとしていることを実行する権限がないことを意味します。
一般的な原因は次のとおりです。
- OAuth トークンに必要なスコープがない (たとえば、
tickets:readを持つトークンはチケットを作成できません) - エンドユーザーの認証情報を使用して、エージェント専用のエンドポイントを呼び出している
- 別のブランドに属するリソースにアクセスしようとしている
- アカウントで IP 制限が有効になっている
- エージェントアカウントが一時停止またはダウングレードされた
403 を受け取った場合は、まず OAuth スコープを確認してください。スコープはトークンの作成後に変更できないため、正しい権限を持つ新しいトークンを生成する必要があります。
簡単な診断アプローチ
アクセス問題をデバッグする場合：
- まず curl でテストして、アプリケーションコードから問題を分離します
- 正しいサブドメインを使用していることを確認します (サンドボックスと本番環境のトークンは互換性がありません)
- 認証方法がトークンタイプと一致していることを確認します
- ユーザーロールを確認します (多くのエンドポイントにはエージェントまたは管理者権限が必要です)
- OAuth の場合は、トークンに必要なスコープが含まれていることを確認します
レート制限とスロットリング：429 エラーの処理
Zendesk は、API の安定性を確保するためにレート制限を実施しています。これらの制限を超えると、429 エラー が表示されます。レスポンスには、再試行するまでに待機する秒数を示す Retry-After ヘッダーが含まれています。
Zendesk は、すべてのリクエストでレート制限ヘッダーも返します。
X-Rate-Limit: 700
X-Rate-Limit-Remaining: 699
レート制限はプランによって異なります。Team プランは 1 分あたり 200 件のリクエスト、Professional プランは 400 件、Enterprise プランは 700 件、Enterprise Plus プランは 2,500 件のリクエストを取得します。一括エンドポイントと検索には、より低い制限があります。
レート制限を処理するためのベストプラクティス
コードに指数バックオフを実装します。
import time
import requests
def make_request_with_retry(url, headers, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 429:
retry_after = int(response.headers.get('Retry-After', 60))
time.sleep(retry_after)
continue
return response
raise Exception("Max retries exceeded")
バッチ処理の場合：
- 可能な場合は一括エンドポイントを使用します (1 つのリクエストとしてカウントされますが、複数のレコードを処理します)
- トラフィックをスムーズにするためにリクエストキューイングを実装します
X-Rate-Limit-Remainingヘッダーを監視し、事前にスロットリングします- 大規模なデータセットの場合は、オフセットベースのページネーションの代わりにカーソルベースのページネーションを使用することを検討してください
データ検証と競合エラー：422 と 409
422 処理できないエンティティ
422 エラー は、リクエストが構文的に有効な JSON であるが、セマンティックに正しくないことを意味します。サーバーは、ビジネスロジックの制約により、それを処理できません。
一般的なシナリオ：
- すでに閉じられているチケットを閉じようとしている
- 必須フィールド (件名やコメント本文など) がありません
- 無効なフィールド値 (存在しないエージェントへの割り当て)
- ビジネスルール違反 (過去の期日の設定)
エラーレスポンスには通常、具体的に何が失敗したかについての詳細が含まれています。
{
"error": "RecordInvalid",
"description": "レコード検証エラー",
"details": {
"base": [
{
"description": "ステータス：クローズはチケットの更新には無効です"
}
]
}
}
409 競合
409 エラー は、リソースの現在の状態との競合を示しています。これは通常、2 つのリクエストが同じリソースを同時に変更しようとした場合に発生します。
409 エラーを防ぐには：
- 可能な場合は、同じリソースを変更するリクエストをシリアル化します
- 重複を作成せずに安全に再試行するために、POST リクエストに
Idempotency-Keyヘッダーを使用します - 更新前に
updated_atタイムスタンプを確認して、楽観的ロックを実装します
べき等キーの使用方法を次に示します。
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-d '{"ticket": {"subject": "Test", "comment": {"body": "Test"}}}' \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-key-123" \
-v -u email/token:token -X POST
キーは 2 時間後に期限切れになります。異なるパラメーターでキーを再利用すると、エラーが返されます。
メール配信ステータスコード
メール通知 API を使用する場合、標準の HTTP レスポンスを超える配信ステータスコードが表示されます。これらは、Zendesk が受信者にメールを送信した後に何が起こったかを示します。
API は、各受信者の id、name、code、および message プロパティとともに配信ステータス情報を返します。表示される最も一般的なコードを次に示します。
| ID | 名前 | SMTP コード | 意味 |
|---|---|---|---|
| 0 | NONE | 0 | まだ配信応答を受信していません |
| 5 | DELIVERED | 200 | メールは正常に配信されました |
| 16 | BAD_EMAIL_ADDRESS | 510 | メールアドレスが拒否されました (存在しないか、スペルが間違っています) |
| 29 | MAILBOX_UNAVAILABLE | 550 | メールボックスが利用できないか、アクセスが拒否されました |
| 31 | MAILBOX_FULL | 552 | 受信者の受信トレイがいっぱいです |
| 39 | USER_DOES_NOT_EXIST | 550 5.1.1 | ユーザーが存在しません (スペルミスを確認してください) |
| 40 | RECIPIENT_IS_INACTIVE | 550 5.2.1 | メールアドレスが無効です |
| 52 | INCORRECT_AUTHENTICATION_LEVEL | 550 5.7.515 | 認証要件が満たされていません |
Microsoft Exchange 接続には、独自のエラーコードがあります。
| コード | 意味 |
|---|---|
| EC-001 | Exchange 接続が非アクティブまたは制限されています |
| EC-002 | Exchange サーバーのストレージが不足しています |
| EC-003 | 一般的な Exchange エラー |
| EC-004 | 受信者のアドレスが無効です |
| EC-005 | Microsoft API の制限に達しました |
| EC-006 | Exchange 認証の問題 |
メール配信の問題をトラブルシューティングする場合は、API レスポンス の delivery_status オブジェクトを確認してください。code フィールドには SMTP ステータスコードが含まれており、message には人間が読める説明が記載されています。
Zendesk API エラーのトラブルシューティングのベストプラクティス
エラーが発生した場合は、次の体系的なアプローチに従ってください。
-
まずステータスコードを確認してください。 どのような種類の問題に対処しているかを大まかに示します。
-
エラーメッセージを読んでください。 Zendesk のエラーレスポンスには、説明的なメッセージが含まれています。ステータスコードを確認して推測するだけではいけません。
-
curl でテストします。 アプリケーションコードをデバッグする前に、認証情報とリクエスト形式が単純な curl コマンドで機能することを確認してください。これにより、API の問題がアプリケーションのバグから分離されます。
-
X-Zendesk-Request-Id ヘッダーを確認してください。 すべてのレスポンスには、この一意の識別子が含まれています。Zendesk サポートに連絡する場合は、この ID を含めて、ログで特定のリクエストを追跡できるようにしてください。
-
サブドメインを確認してください。 API トークンは、特定のサブドメインにスコープ設定されています。
company.zendesk.comのトークンは、company-sandbox.zendesk.comでは機能しません。 -
認証方法を確認してください。 基本認証、OAuth、および JWT を混在させると、混乱の原因となることがよくあります。ヘッダー形式がトークンタイプと一致していることを確認してください。
-
CORS の問題を確認してください。 Zendesk REST API は、ブラウザーオリジンの認証をサポートしていません。クライアント側の JavaScript リクエストは失敗します。代わりに、バックエンドサービスまたは ZAF クライアントを備えた Zendesk アプリを使用してください。
避けるべき一般的な間違い：
- 基本認証のユーザー名で
/tokenサフィックスを省略する - Bearer の代わりに基本認証ヘッダーで OAuth トークンを送信する
- エージェント専用のエンドポイントにエンドユーザーの認証情報を使用する
- 適切な再試行ロジックで 429 エラーを処理しない
- レート制限されたレスポンスで
Retry-Afterヘッダーを無視する
eesel AI で Zendesk API エラーを自動的に処理する
API エラーへの対処は、どのプラットフォームでも構築する上での一部ですが、複雑さを全体的に軽減できるとしたらどうでしょうか？eesel AI は、Zendesk インスタンスの AI チームメイトとして機能し、チケット操作をインテリジェントに処理するため、最初から API 呼び出しの回数を減らすことができます。
仕組みは次のとおりです。API を酷使し、レート制限のリスクがあるカスタム連携を構築する代わりに、eesel AI をチームに招待します。過去のチケット、ヘルプセンターの記事、およびマクロから学習し、最前線のサポートを自律的に処理します。これは、API 呼び出しの回数が減り、429 エラーが減り、認証問題のデバッグに費やす時間が短縮されることを意味します。
eesel AI が Zendesk と対話する必要がある場合、組み込みのエラー処理と再試行ロジックが含まれています。レート制限、一時的な障害、および競合エラーは自動的に管理されます。平易な英語でエスカレーションルールを定義すると (「常に請求に関する紛争を人にエスカレーションする」)、eesel AI はそれに従います。
Zendesk で構築するチームにとって、このアプローチは API エラーのカテゴリ全体を排除します。指数バックオフを実装したり、OAuth スコープを管理したり、401 レスポンスをデバッグしたりする必要はありません。eesel AI は統合の複雑さを処理し、より優れた顧客体験の提供に集中できます。
API エラーのトラブルシューティングにうんざりしていて、AI チームメイトが Zendesk の運用をどのように簡素化できるかを知りたい場合は、eesel AI を無料で試す か、デモを予約する して、実際に動作を確認してください。
よくある質問
この記事を共有
Article by
Stevia Putri
Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.
