データエクスポートAPIのトラブルシューティング
このトピックでは、Data Export API でよく発生するエラー応答の解釈方法、および各エラーについて最も可能性の高い原因と対処法を確認します。すべてのエラー応答には、
code、message、および数値のstatusCodeが含まれています。codeの値によって、具体的な条件が特定されます。認証および認可のエラー
| エラーコード | 考えられる原因 | おすすめ |
|---|---|---|
ERR_INVALID_APIKEY(401) |
x-api-keyヘッダーが欠落しているか、形式が不正か、有効期限が切れているか、または削除されています。また、鍵が作成または更新された直後、新しい鍵が登録される前の短い間（通常は1分未満）にも発生します。 |
リクエストに、完全なAPIキー値を含むx-api-keyヘッダーが含まれていることを確認してください。Account Administration にて、キーがまだ存在し、有効期限が切れていないことを確認してください。鍵が作成されたばかり、または更新されたばかりの場合は、1分間待ってから再度お試しください。 |
ERR_UNAUTHORIZED_PRINTERS(403) |
このリクエストには、APIキーでアクセスできない1つ以上のprinterId値が含まれています。 |
同じAPIキーを使用して/printersを呼び出し、利用可能なプリンターを正確に確認してから、それらのプリンターIDのみを指定してリクエストを再度送信してください。 |
ERR_TENANT_NOT_FOUND(404) |
APIキーは認識されていますが、有効なアカウントに関連付けられていません。アカウントが削除された場合や、設定が間違っている場合などに、このような現象が発生することがあります。 | Ricohのアカウント担当者に連絡し、テナントが有効であること、およびAPIキーがそのテナントに関連付けられていることをご確認ください。 |
パラメータの検証エラー（400 不正な要求）
パラメータの検証エラーが発生するたびに、400のステータスコードが返されます。このcode値は、具体的な問題を特定するものです。
| エラーコード | 考えられる原因 | おすすめ |
|---|---|---|
ERR_MISSING_PRINTER_ID |
このリクエストには、printerIdの値が一切含まれていませんでした。/jobs、/printer-states、および/printer-interventions には、少なくとも1つが必要です。 |
printerIdクエリパラメータを少なくとも 1 つ追加してください。複数のプリンターを含めるには、このパラメータを繰り返してください。 |
ERR_INVALID_PRINTER_ID_FORMAT |
printerIdの値は有効な UUID ではありません。 |
その値を、/printers からの応答と照らし合わせてご確認ください。よくある間違いとしては、余分な空白、文字の抜け、あるいはプリンターIDの代わりにプリンター名を貼り付けてしまうことなどが挙げられます。 |
ERR_INVALID_TIMEZONE |
timezoneの値が指定されていません、または有効なIANAタイムゾーン識別子ではありません。 |
America/DenverやEurope/Bucharestといった地域ベースの識別子をご使用ください。MSTやESTなどの3文字の略語は受け付けられません。インタラクティブなドキュメントページには、有効な値のリストがあります。 |
ERR_INVALID_DATE_FORMAT |
startDateTimeまたはendDateTimeの値が、指定された形式と一致していません。 |
YYYY-MM-DDTHH:MM:SS の形式を使用してください。必要に応じて、.sssというミリ秒の接尾辞を付けることもできます。UTCオフセットやZの接尾辞は含めないでください。タイムゾーンは、timezoneパラメータで別途指定されます。 |
ERR_INVALID_DATE_RANGE |
startDateTime はendDateTime と同じか、それ以降です。 |
指定されたタイムゾーンにおいて、startDateTimeがendDateTimeより前であることを確認してください。 |
ERR_DATE_RANGE_EXCEEDED |
startDateTimeとendDateTimeの間の期間が、許可されている最大範囲を超えています。 |
要求された時間枠の範囲を縮小してください。チャンキングに関するガイダンスについては、データエクスポートAPIのレスポンス制限への対応をご覧ください。 |
ERR_INVALID_JOB_STATE |
jobStateの値が、許容される値のいずれにも該当しません。 |
printing、printed、aborted、completedのいずれかを使用してください。なお、completedには、printedジョブとabortedジョブの両方が含まれます。 |
ERR_INVALID_STATE_CATEGORY |
stateCategoryの値が、許容される値のいずれにも該当しません。 |
up、down、またはidleのいずれかを選択してください。 |
ERR_INVALID_LANGUAGE |
/printer-interventionsに指定されたlanguage値は、許容される値のいずれにも該当しません。 |
en、de、ja、it、fr、またはesのいずれかをお選びください。このエラーは、コード自体が拒否されたことを意味します。受け入れられたものの、特定の説明文に対する翻訳がないコードであっても、APIがその説明文を英語のまま返すため、エラーにはなりません。 |
ERR_INVALID_BOOLEAN_PARAM |
currentStateまたはstateCategoryOnlyパラメータの値がtrueまたはfalse 以外になっています。 |
リテラルとして小文字のストリングtrueまたはfalseを使用してください。 |
ERR_UNKNOWN_PARAMETERS |
このリクエストには、エンドポイントが受け付けないパラメータが1つ以上含まれています。 | インタラクティブドキュメントでリストされているエンドポイントのパラメータと、リクエストの内容を照らし合わせてご確認ください。一般的な原因としては、入力ミス、別のエンドポイント向けのパラメータ、あるいはHTTPクライアントによって追加された余分なトラッキングパラメータなどが挙げられます。 |
ERR_DUPLICATE_PARAMETERS |
同じパラメータが複数回指定されていますが、そのパラメータについてエンドポイントは重複を受け付けません。 | パラメータリストをご確認ください。printerIdパラメータは重複しても構いません（プリンタごとに1回まで）。その他のパラメータは、最大1回のみ指定する必要があります。 |
ERR_EMPTY_PARAMETERS |
必須のパラメータが存在しますが、値が指定されていません。 | すべての必須パラメータに、空ではない値が設定されていることを確認してください。 |
ERR_INVALID_TENANT_ID |
APIキーに関連付けられているテナント識別子が無効です。 | Ricohのアカウント担当者に連絡してください。 |
応答サイズおよびメソッドのエラー
| エラーコード | 考えられる原因 | おすすめ |
|---|---|---|
ERR_RESPONSE_LIMIT_EXCEEDED(413) |
リクエストに一致するデータは、最大レスポンスサイズを超過してしまいます。レスポンス本文には、適用されている制限を示すmaxJobsフィールドが含まれています。 |
日付の範囲を絞り込むか、印刷機の数を減らすか、あるいはその両方を行ってから、再度リクエストを送信してください。推奨されるチャンキングパターンについては、データエクスポートAPIのレスポンス制限への対応をご覧ください。 |
ERR_UNSUPPORTED_METHOD(405) |
このリクエストでは、GET 以外の HTTP メソッドが使用されました。 |
データエクスポートAPIでは、GETメソッドのみがサポートされています。クライアントを更新して、GETを使用するようにしてください。 |
サーバーエラー（500 サーバー内部エラー）
500件の応答は、サーバーで予期せぬ条件が発生していることを示しています。Data Export API のすべてのエンドポイントがGETリクエストであり、副作用を伴わないため、再試行は安全です。再試行する前に数秒間お待ちください。エラーが続く場合は、指数関数的なバックオフを行ってください。
| エラーコード | 考えられる原因 | おすすめ |
|---|---|---|
ERR_INTERNAL_SERVER_ERROR |
サーバーで予期せぬ条件が発生しました。 | 数秒待ってから、もう一度お試しください。エラーが数分以上続く場合は、Ricohのアカウント担当者に連絡してください。 |
ERR_TENANT_CHECK_FAILED |
サーバーは、APIキーに関連付けられているテナントを確認できませんでした。 | 数秒待ってから、もう一度お試しください。それでもエラーが解消されない場合は、Ricohのアカウント担当者に連絡してください。 |
ERR_PRINTERS_FETCH_FAILED |
サーバーは、そのテナントのプリンターのリストを取得できませんでした。 | 数秒待ってから、もう一度お試しください。それでもエラーが解消されない場合は、Ricohのアカウント担当者に連絡してください。 |
ERR_PRINTER_STATES_FETCH_FAILED |
サーバーは、このリクエストに関するプリンターの状態データを取得できませんでした。 | 数秒待ってから、もう一度お試しください。それでもエラーが解消されない場合は、Ricohのアカウント担当者に連絡してください。 |
その他の症状
- レスポンスが空（
[]）ですが、データがあるはずなのです - 空の配列は、リクエストに一致するレコードがないことを意味します。時間範囲（APIでは過去7日分のみが提供されます）、タイムゾーン、
printerIdの値、およびjobStateやstateCategoryなどのフィルター条件を確認してください。 - レスポンスに含まれる日付と時刻の値が、ご期待の内容と一致していません
- レスポンスのタイムスタンプは、リクエストで指定されたタイムゾーンに基づく現地時間です。同じリクエストを異なる
timezoneの値で送信すると、同じイベントを表しているにもかかわらず、異なるタイムスタンプストリングが生成されます。Data Export API における日付と時刻の処理を参照してください。 /printersのレスポンスにプリンターが1台欠けています- このAPIは、データコレクターによって監視されているプリンターのみを返します。プリンターが見つからない場合は、そのプリンターがデータコレクターに登録されており、現在接続されていることを確認してください。
- プリンタの状態応答には、
unknownなカテゴリが含まれています unknownというカテゴリは、プリンタの生状態を分類できなかったことを示しています。状態とカテゴリの完全な対応関係については、プリンターの状態と状態のカテゴリーをご覧ください。