エラーと回数制限
API が定義する JSON エラーは {"error":{"code":"…","message":"…"}} の形式です。処理分岐には code を使ってください。
| code | HTTP | 対処 |
|---|---|---|
UNAUTHORIZED | 401 | Bearer がない、不正、停止中、失効済み、または期限切れ。トークンを確認してください。 |
INSUFFICIENT_SCOPE | 403 | エンドポイントに応じて audit:read（監査ログ API）または reports:read（評価結果 API）が必要です。設定の「プランと API」で発行したトークンを使ってください。 |
PLAN_NOT_ELIGIBLE | 403 | 対象組織のプランが Business / MSP ではありません。 |
IP_DENIED | 403 | 接続元 IP が組織の許可範囲外です。許可されたネットワークから接続してください。 |
INVALID_PARAMETER | 400 | 未知のパラメータ、または同じパラメータの重複があります。 |
INVALID_LIMIT | 400 | limit が許容範囲の整数ではありません。 |
INVALID_TIME | 400 | 日時の形式・日付が不正、または since が until より後です。 |
INVALID_CURSOR | 400 | cursor が不正・改変済み、または別組織向けです。保存した時間窓から取得し直してください。 |
NOT_FOUND | 404 | 評価結果 API のみです。指定した評価結果は存在しないか、別組織に属します。 |
RATE_LIMITED | 429 | 回数制限に達しました。Retry-After の秒数だけ待って同じ要求を再試行してください。 |
回数制限
監査ログ API と評価結果 API の合計で、トークンあたり毎分 60 回、認証前の接続元 IP あたり毎分 120 回です。IP の判定は Bearer の形式を確認した後、トークンをデータベースで照合する前に行います。同じ接続元を共有する収集処理は同じ IP 枠を使います。
アプリ側の上限を超えた場合は HTTP 429 と Retry-After（秒）を返します。その秒数を待って同じページを再試行してください。途中のエラーでチェックポイントを進めないでください。通信エラーや JSON 以外の応答も成功として扱わないでください。
前段の Web サーバーも /api/v1/ に接続元 IP あたり毎分 120 回の制限を適用し、短時間の集中は 20 回まで許容します。前段の 429 もアプリの 429 と同じ JSON 本文と Retry-After を返します。本文だけでは応答元を区別できませんが、区別する必要はありません。どちらも Retry-After の秒数だけ待って同じ要求を再試行してください。