Telm mengukur API dengan dua cara: sebuah batas laju per-menit (batas lonjakan) dan sebuah kuota harian (anggaran total Anda untuk satu hari UTC). Keduanya berskala menurut paket. Setiap respons yang diukur mengembalikan X-Quota-Limit, X-Quota-Used, dan X-Quota-Reset sehingga Anda selalu tahu sisa anggaran Anda, dan kedua batas mengembalikan 429 dengan header Retry-After ketika terlampaui.
1Dua batas: laju per-menit dan kuota harian
Ada dua batas terpisah. Batas laju per-menit membatasi berapa banyak permintaan yang dapat Anda buat dalam satu menit mana pun, meratakan lonjakan. Kuota harian adalah anggaran keseluruhan Anda: ia membatasi berapa banyak panggilan terukur yang dapat Anda buat sepanjang satu hari UTC.
Keduanya independen. Anda dapat mencapai batas per-menit sementara masih memiliki banyak sisa kuota harian (Anda sekadar mengirim terlalu cepat), atau menghabiskan kuota harian Anda sementara jauh di bawah batas per-menit (Anda telah memakai habis harinya). Keduanya mengembalikan status 429, tetapi karena alasan berbeda — periksa kode kesalahan di body untuk membedakan mereka.
- Batas laju per-menit — batas lonjakan, diatur ulang setiap menit.
- Kuota harian — total panggilan terukur Anda untuk hari itu, diatur ulang pada tengah malam UTC.
- Kuota dihitung sekali per akun, dibagi di seluruh kunci Anda.
2Kuota harian menurut paket
Kuota harian Anda adalah jumlah panggilan API terukur yang dapat Anda buat per hari UTC, dan itu bergantung pada paket Anda. Penghitung dibagi di seluruh kunci Anda dan mengikuti paket terbaik di antara grup yang Anda kelola — tanpa langganan berbayar, Anda berada di tingkat Free.
Jendelanya adalah hari kalender UTC, jadi penghitung terpakai Anda diatur ulang ke nol pada tengah malam UTC. Sebuah pemeriksaan spam batch berbiaya satu panggilan per item dalam batch, bukan satu panggilan untuk seluruh permintaan.
- Free — 100 panggilan per hari.
- Basic — 1.000 panggilan per hari.
- Pro — 10.000 panggilan per hari.
- Business — 50.000 panggilan per hari.
3Batas laju per-menit menurut paket
Di atas kuota harian, setiap kunci API dibatasi ke sejumlah permintaan per menit sesuai tingkat paketnya. Ini adalah batas perataan: ia menghentikan satu klien dari mengirim lonjakan besar dalam satu detik, bahkan ketika anggaran harian jauh dari habis.
Terpisah dari itu, batas per-IP dan per-akun yang luas berlaku di seluruh API untuk menjaga platform tetap stabil. Dalam penggunaan normal — permintaan yang mantap dan terukur — Anda tidak akan pernah menyentuh ini; mereka hanya terpicu pada lonjakan yang menyalahgunakan.
- Free dan Basic — 60 permintaan per menit.
- Pro — 600 permintaan per menit.
- Business — 1.800 permintaan per menit.
- Sebarkan permintaan alih-alih menembakkan semuanya sekaligus.
4Membaca sisa anggaran Anda
Anda tidak perlu menebak berapa banyak kuota yang tersisa. Setiap respons yang diukur — berhasil atau gagal — menyertakan tiga header: X-Quota-Limit (batas harian Anda), X-Quota-Used (berapa banyak panggilan yang telah Anda habiskan hari ini), dan X-Quota-Reset (saat, dalam UTC, ketika penghitung diatur ulang).
Endpoint pemeriksaan spam juga menggemakan angka yang sama di dalam body respons di bawah sebuah objek quota, sehingga Anda dapat membaca sisa anggaran Anda tanpa mengurai header. Gunakan ini untuk mengatur laju permintaan Anda sendiri dan memperingatkan diri Anda sebelum kehabisan.
- X-Quota-Limit — batas panggilan harian Anda.
- X-Quota-Used — panggilan yang dihabiskan sejauh ini hari ini.
- X-Quota-Reset — waktu pengaturan ulang dalam UTC (RFC 3339).
- Respons pemeriksaan spam juga menyertakan objek quota dengan bidang yang sama.
5Apa yang terjadi pada 429
Ketika Anda melewati salah satu batas, API mengembalikan HTTP 429 dengan header Retry-After yang memberi tahu Anda berapa detik harus menunggu. Untuk batas laju per-menit, Retry-After sekitar satu menit. Untuk kuota harian, body membawa kode daily_quota_exceeded plus paket Anda, batas, jumlah terpakai, waktu pengaturan ulang, dan petunjuk peningkatan, dan Retry-After menghitung mundur ke tengah malam UTC.
Cara yang tepat untuk menangani 429 adalah mundur dan mencoba ulang setelah penundaan Retry-After, bukan menggempur endpoint. Klien yang berperilaku baik membaca header dan berhenti sejenak; klien yang terus mencoba ulang seketika hanya tetap terblokir.
- 429 rate_limit_exceeded — Anda mengirim terlalu cepat; tunggu sekitar satu menit.
- 429 daily_quota_exceeded — harinya habis; tunggu sampai pengaturan ulang UTC atau tingkatkan.
- Selalu hormati header Retry-After sebelum mencoba ulang.