Watch-IP

Error dan rate limit

Setiap endpoint Watch-IP mengembalikan error dalam bentuk yang sama dan menerapkan rate limit dengan cara yang sama, apa pun produk yang Anda panggil.

Bentuk respons error

Respons non-2xx selalu berupa objek JSON dengan error (kode yang stabil dan bisa dibaca mesin) dan message (deskripsi yang bisa dibaca manusia). error tetap konstan di seluruh versi API; teks message bisa berubah, jadi cocokkan berdasarkan error, bukan message.

Respons error

{
  "error": "invalid_ip",
  "message": "\"999.999.999.999\" is not a valid IPv4 or IPv6 address."
}

Kode status yang umum

Kumpulan kode persis yang bisa dikembalikan sebuah endpoint didokumentasikan di halaman referensinya masing-masing; berikut ini adalah kode yang berlaku di seluruh API.

400
Input yang salah bentuk — alamat IP tidak valid, batch yang kosong atau melebihi batas (POST /v1/lookup mengizinkan hingga 100 IP), atau field wajib yang hilang.
401
API key hilang atau tidak valid.
403
Jenis key salah untuk rute ini (publishable key pada endpoint secret-key, atau sebaliknya), atau — khusus untuk GET /v1/geo dan POST /v1/email/validate — Origin/Referer yang tidak ada di daftar allowed-origins key tersebut. Pada kasus origin, tidak ada header CORS yang diset juga, sehingga browser memblokir respons terlepas dari isi ini.
422
Input yang valid secara semantik tapi tidak bisa diproses — saat ini hanya POST /v1/risk/check, ketika IP yang dikirim tidak bisa diselesaikan ke sebuah lokasi.
429
Rate limit terlampaui untuk jendela satu menit saat ini.

Rate limit

Rate limit diterapkan per akun pelanggan dalam jendela tetap satu menit, dibagi bersama di antara semua endpoint yang Anda panggil, bukan dilacak per rute. Batas ini menghitung panggilan HTTP, bukan item: POST /v1/lookup dan POST /v1/email/batch dihitung sebagai satu request baik berisi 1 maupun 100 entri, begitu pula membuat, memeriksa status, dan mengunduh list job email. Respons 429 karena rate limit (error: "rate_limit_exceeded") menyertakan header Retry-After yang berisi jumlah detik hingga jendela saat ini direset — tunggu selama itu, lalu coba lagi.

Mencoba lagi dengan aman

GET /v1/geo, GET /v1/lookup/{ip}, POST /v1/lookup, dan POST /v1/email/validate bersifat read-only dan aman untuk dicoba lagi segera setelah error jaringan. POST /v1/risk/check secara default memperbarui baseline yang tersimpan — kirim commit:false terlebih dahulu jika Anda butuh percobaan spekulatif yang tidak boleh mengubahnya.

Halaman terkait