エラーとレート制限
Watch-IPのすべてのエンドポイントは、呼び出す製品にかかわらず同じ形式でエラーを返し、同じ方法でレート制限を適用します。
エラーレスポンスの形式
2xx以外のレスポンスは常に、error(安定したマシン可読のコード)とmessage(人間が読める説明)を持つJSONオブジェクトです。errorはAPIバージョンをまたいで一定ですが、messageのテキストは変更される可能性があるため、messageではなくerrorで判定してください。
エラーレスポンス
{
"error": "invalid_ip",
"message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}共通のステータスコード
エンドポイントが返しうるコードの正確な一覧はそれぞれのリファレンスページに記載されています。以下はAPI全体で共有されるものです。
- 400
- 不正な入力—無効なIPアドレス、空または大きすぎるバッチ(POST /v1/lookupは最大100件のIPを許可)、または必須フィールドの欠落。
- 401
- APIキーが欠落しているか無効です。
- 403
- このルートに対して誤った種類のキーが使われています(シークレットキー用エンドポイントで公開可能キーを使う、またはその逆)。あるいは—GET /v1/geoとPOST /v1/email/validateに限り—Origin/Refererがキーの許可オリジンリストにありません。オリジンが原因の場合はCORSヘッダーも設定されないため、この本文の内容にかかわらずブラウザがレスポンスをブロックします。
- 422
- 意味的には有効だが処理できない入力—現在はPOST /v1/risk/checkのみで、指定されたIPを位置情報に解決できない場合に発生します。
- 429
- 現在の1分間ウィンドウでレート制限を超えました。
レート制限
レート制限は、ルートごとではなく呼び出すすべてのエンドポイントで共有される、顧客アカウント単位の固定1分間ウィンドウで適用されます。この制限はアイテム数ではなくHTTP呼び出し数で数えます。POST /v1/lookupとPOST /v1/email/batchは、含まれるエントリが1件でも100件でも1リクエストとして数えられます。メールリストジョブの作成、状態確認、結果のダウンロードも同様です。レート制限による429(error: "rate_limit_exceeded")には、現在の時間枠がリセットされるまでの秒数を示すRetry-Afterヘッダーが含まれます。その秒数だけ待ってから再試行してください。
安全な再試行
GET /v1/geo、GET /v1/lookup/{ip}、POST /v1/lookup、POST /v1/email/validateは読み取り専用で、ネットワークエラーの直後に再試行しても安全です。POST /v1/risk/checkはデフォルトで保存済みのベースラインを更新します—ベースラインを動かしたくない投機的な再試行が必要な場合は、先にcommit:falseを指定してください。