Batas laju permintaan

Batas permintaan per paket yang berlaku di Listings dan Social, struktur respons 429, serta cara menerapkan jeda dan mencoba ulang.

Listings API menghitung permintaan per akun berdasarkan batas laju permintaan paket Anda. Tetap berada dalam batas tersebut membuat integrasi Anda tetap responsif; melampauinya akan mengembalikan 429 Too Many Requests beserta semua informasi yang Anda perlukan untuk mencoba ulang dengan lancar.

Batas per paket

Mencoba API tanpa paket berbayar? Akses harian sandbox gratis mengembalikan batas permintaan yang berlaku beserta kunci API saat Anda mulai menggunakan akses tersebut.

Batas ditentukan berdasarkan paket dan diberlakukan per akun: setiap kunci API dalam satu akun menggunakan kuota yang sama. Permintaan dihitung dalam tiga rentang waktu: batas lonjakan per menit, batas per jam, dan batas harian. Setiap permintaan menggunakan kuota yang sama, apa pun endpoint-nya. Uji coba gratis menggunakan paket yang Anda pilih, sehingga batas paket tersebut berlaku sejak permintaan pertama.

Social menggunakan kuota yang sama

Permintaan ke endpoint Social dihitung terhadap kuota permintaan per akun yang sama dengan semua permintaan lainnya. Satu POST /social/bulk-posts yang memuat 500 baris dihitung sebagai satu permintaan, bukan 500, sehingga operasi massal merupakan cara paling hemat kuota untuk memuat banyak konten.

Listings dan Social merupakan langganan terpisah, tetapi kuotanya tidak terpisah. Akun yang memiliki keduanya mendapatkan batas yang lebih tinggi dari kedua tingkatan paket tersebut, yang diberlakukan satu kali untuk seluruh endpoint — bukan dijumlahkan, dan bukan satu kuota per produk. Seluruh lalu lintas permintaan pelanggan yang menggunakan Listings Launch dan Social Growth dihitung berdasarkan batas Growth di atas.

Respons 429

Saat Anda melampaui batas, API mengembalikan status HTTP 429 beserta respons kesalahan standar. Tiga field penting untuk percobaan ulang:

• retry_after_seconds: waktu tunggu sebelum mencoba ulang. Header HTTP Retry-After memuat nilai yang sama jika tersedia.
• correlation_id: pengenal permintaan yang perlu Anda sertakan jika menghubungi dukungan.
• doc_url: tautan kembali ke entri rate_limited dalam referensi kode kesalahan.

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

Menangani respons 429 dengan jeda percobaan ulang

Patuhi retry_after_seconds jika tersedia, dan jika tidak, tingkatkan jeda secara eksponensial: gandakan jeda pada setiap 429 yang diterima berturut-turut hingga batas maksimum, dengan sedikit variasi acak agar sekumpulan klien tidak mencoba ulang secara serentak.

import randomimport time import requests MAX_RETRIES = 5  def get_with_backoff(url: str, headers: dict, max_retries: int = MAX_RETRIES):    for attempt in range(max_retries):        resp = requests.get(url, headers=headers)        if resp.status_code != 429:            resp.raise_for_status()            return resp.json()         # Prefer the server's hint; fall back to exponential backoff + jitter.        body = resp.json().get("error", {})        retry_after = body.get("retry_after_seconds")        if retry_after is None:            retry_after = min(2 ** attempt, 30) + random.uniform(0, 1)        time.sleep(retry_after)     raise RuntimeError("Still rate limited after retrying")

Tetap di bawah batas

• Minta satu halaman pada satu waktu: perulangan paginasi paralel dengan jeda sangat singkat merupakan penyebab paling umum respons 429. Baca pageInfo.hasNextPage dan ambil halaman berikutnya hanya setelah respons untuk halaman saat ini diterima.
• Lakukan pemfilteran di sisi server dengan parameter kueri filter alih-alih mengambil setiap halaman lalu membuang baris di sisi klien.
• Simpan respons yang jarang berubah dalam cache alih-alih mengambilnya kembali pada setiap permintaan.