Rate limits

Setiap permintaan dengan sebuah API key dihitung dua kali: sekali di bucket per menit dan sekali di bucket per hari. Melampaui salah satunya mengembalikan 429.

Batas Anda

curl https://api.mageran.ai/api/v1/balance \
  --header 'x-mager-api-key: YOUR_API_KEY'

"rateLimit": {
  "perMinute": 60,
  "perDay": 5000,
  "accountPerMinute": 60,
  "accountPerDay": 5000
}

• perMinute / perDay adalah batas yang berlaku untuk key yang Anda pakai.
• accountPerMinute / accountPerDay adalah batas bawaan akun. Sebuah key mewarisi nilai ini kecuali key tersebut punya override sendiri.

Cara penghitungannya

Bucket-nya berupa fixed window, bukan sliding window. Bucket menit direset tiap pergantian menit; bucket harian direset tengah malam UTC. Lonjakan di 10:00:59 dan satu lagi di 10:01:00 masuk ke bucket yang berbeda.

Semua permintaan terautentikasi ikut dihitung, termasuk GET /balance dan setiap polling ke sebuah task. Polling sebuah task tiap detik selama dua menit menghabiskan 120 permintaan hanya untuk satu generasi.

Menangani 429

{
  "error": {
    "statusCode": 429,
    "message": "Rate limit exceeded"
  }
}

Response-nya tidak membawa header Retry-After, jadi atur backoff sendiri:

1. Tunggu, lalu coba lagi dengan exponential backoff dan jitter — mulai sekitar satu detik, batasi maksimal satu menit.
2. Jangan langsung mengulang dalam loop. Retry loop yang rapat justru membuat Anda tetap kena rate limit.
3. Kalau yang tercapai adalah batas harian, backoff tidak akan menolong. Antrikan pekerjaannya dan lanjutkan besok, atau ajukan kenaikan batas.

Cara tetap di bawah batas

• Pakai webhook, bukan polling. Satu callback menggantikan puluhan permintaan GET.
• Polling tiap 3–5 detik, bukan terus-menerus.
• Cache GET /models dan GET /templates. Keduanya jarang berubah; tidak ada alasan mengambilnya di tiap aksi pengguna.
• Pakai key terpisah untuk beban kerja yang terpisah, masing-masing dengan batasnya sendiri, supaya batch job tidak menghabiskan jatah trafik interaktif Anda.

Butuh ruang lebih? Batasnya berlaku per key dan per akun, dan keduanya bisa dinaikkan. Ajukan lewat dashboard.