Batas laju dan kuota

Dua jenis batas menjaga API tetap cepat bagi semua orang:

• Batas laju sebuah kunci: berapa banyak permintaan per detik yang boleh dikirimnya, dengan lonjakan untuk puncak singkat.
• Kuota organisasi: berapa banyak permintaan yang boleh dikirim semua kuncinya bersama-sama per menit, per hari, dan per bulan.

Keduanya bergantung pada paket organisasi. Setiap respons memberi tahu posisi Anda, jadi klien yang berperilaku baik tidak pernah perlu menebak.

Batas laju sebuah kunci

Setiap kunci mendapat laju tetap dan lonjakan. Lonjakan memungkinkan Anda mengirim sejumlah permintaan itu sekaligus; setelah itu, permintaan diizinkan pada laju tetap.

Kelas ditentukan oleh paket organisasi. GET /v1/me menunjukkan kelas, laju, dan lonjakan kunci yang memanggilnya (rate_limit). Batas ini berlaku untuk kunci secara keseluruhan, berapa pun jumlah server API yang melayani permintaan Anda.

Endpoint stream, POST /v1/chat (dengan atau tanpa "stream": true) dan GET /v1/jobs/stream, berada di luar batas laju kunci: keduanya tidak menghabiskannya, dan header RateLimit keduanya tidak memiliki item "key". Keduanya tetap dihitung terhadap kuota organisasi, masing-masing sekali, saat permintaan dimulai. Pertanyaan memiliki batasnya sendiri, yang dijelaskan di bawah.

Kuota organisasi

Paket dapat menetapkan kuota permintaan untuk organisasi: per menit, per hari, dan per bulan. Jendela waktunya adalah periode kalender dalam UTC: satu menit dimulai pada detik :00, satu hari pada 00:00 UTC, satu bulan pada hari pertama pukul 00:00 UTC. Setiap permintaan dengan kunci atau token OAuth organisasi dihitung, di alamat mana pun. Permintaan stream dihitung sekali, saat dimulai, berapa pun lamanya; jika kuota sudah habis, permintaan itu ditolak dengan 429 seperti permintaan lainnya. Permintaan yang ditolak dengan 429 tidak dihitung.

Header

Setiap respons terhadap permintaan dengan kunci membawa batas yang berlaku untuknya:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy dan RateLimit mengikuti draf IETF RateLimit header fields for HTTP. Setiap item adalah satu batas:

X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset melaporkan batas yang paling ketat di antara batas-batas ini dalam bentuk yang lebih sederhana, untuk klien yang ditulis sebelum RateLimit ada. X-RateLimit-Reset dinyatakan dalam detik.

Saat batas tercapai

API menjawab 429 Too Many Requests dengan header Retry-After dalam detik:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Tunggu selama Retry-After dan ulangi permintaannya. Ulangi POST dan PATCH dengan Idempotency-Key yang sama. Fungsi bantu percobaan ulang di Error melakukan keduanya.

Batas paket lainnya juga menjawab 429 dengan Retry-After, misalnya jumlah pertanyaan per hari (limits.questions) atau jawaban yang sedang diproses pada saat yang sama (limits.concurrent_answers). Tangani batas itu dengan cara yang sama.

Tetap di bawah batas

• Baca RateLimit dan perlambat saat r mulai rendah, alih-alih menunggu 429.
• Sebarkan pekerjaan massal ke rentang waktu yang lebih panjang, dan pakai endpoint batch jika tersedia: satu batch berisi 100 dokumen adalah satu permintaan.
• Jangan melakukan polling perubahan dalam loop yang rapat. Berlangganan webhook, atau baca umpan peristiwa setiap beberapa detik.
• Jalankan worker paralel dengan pembatas bersama. Beberapa proses dengan satu kunci berbagi satu batas laju.
• Tanyakan kepada kontak Anda di Sursa tentang kelas yang lebih tinggi jika integrasi Anda membutuhkan lebih banyak.