Rate limit

Rate limit melindungi saldo Anda dan layanan. Batas dihitung dalam request per menit (RPM) per API key, dan key juga bisa memiliki batas pengeluaran USD harian.

Batas per paket

Upgrade di halaman harga untuk menaikkan batas Anda.

Batas per key

Saat membuat atau mengubah key di API keys, Anda bisa mengatur:

Jendela RPM berdurasi satu menit dan dihitung per key, jadi key terpisah untuk aplikasi yang berbeda tidak berbagi batas, tetapi setiap key tetap dibatasi oleh batas paket Anda.

Header batas laju

Setiap respons generasi (berhasil atau gagal) memberi tahu posisi Anda, sehingga Anda bisa melambat sebelum mencapai batas:

Klien browser juga dapat membacanya (tercantum di Access-Control-Expose-Headers).

Lonjakan dan konkurensi

Permintaan di atas batas tidak langsung ditolak: permintaan menunggu dalam antrean dan dimulai begitu jendela satu menit kosong. Hingga 10 permintaan per akun berjalan bersamaan; sisanya menunggu sampai salah satu selesai. Sebelum dimulai, perkiraan biaya maksimum permintaan dicadangkan dari saldo Anda bersama biaya permintaan yang sedang berjalan, sehingga permintaan paralel tidak pernah menghabiskan lebih dari saldo Anda. Permintaan yang tidak bisa dimulai dalam 60 detik mengembalikan 429 (rate_limited atau concurrency_limit) dengan Retry-After; jika biayanya tidak lagi muat di saldo, mengembalikan 402 insufficient_balance.

Coba ulang yang aman dengan Idempotency-Key

Setelah galat jaringan Anda mungkin tidak tahu apakah permintaan sampai. Kirim header Idempotency-Key (string unik hingga 120 karakter, misalnya UUID) dan ulangi dengan kunci yang sama: jika permintaan pertama sudah dikirim ke model, percobaan ulang mengembalikan 409 idempotency_conflict alih-alih menjalankan dan menagih pekerjaan dua kali. Jika permintaan pertama gagal sebelum mencapai model, kunci dilepas dan percobaan ulang berjalan normal. Satu kunci dapat dipakai sekali per akun selama 24 jam.

curl https://api14.com/api/v1/images/generations \
  -H "Authorization: Bearer $API14_KEY" \
  -H "Idempotency-Key: 6f1c2a3e-order-1842" \
  -H "Content-Type: application/json" \
  -d '{"model": "black-forest-labs/flux-3-image", "prompt": "a red bicycle"}'

Saat Anda mencapai batas

Terlalu banyak request

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "message": "Rate limit of 5 requests per minute exceeded.",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

Tunggu sebanyak detik yang tertera di Retry-After, lalu coba lagi. SDK resmi OpenAI secara otomatis mencoba ulang response 429 dengan backoff (dua kali percobaan ulang secara default; atur dengan maxRetries / max_retries).

Batas pengeluaran harian

{
  "error": {
    "message": "This API key reached its daily spend limit.",
    "type": "rate_limit_error",
    "code": "daily_limit_reached"
  }
}

Mencoba ulang tidak akan membantu sampai hari UTC berikutnya. Naikkan atau hapus batas harian key di API keys jika trafik ini memang wajar.

Batas upstream

Penyedia memiliki batasnya sendiri, yang lebih ketat untuk varian model :free. Saat penyedia membatasi sebuah request, 429 dari penyedia itu diteruskan kepada Anda. Gunakan fallback model atau provider routing untuk menyebarkan beban ke beberapa penyedia.

Menangani batas di kode

• Patuhi Retry-After dan coba ulang dengan exponential backoff dan jitter.
• Bedakan rate_limited (coba lagi nanti) dari daily_limit_reached dan insufficient_balance (mencoba ulang tidak membantu).
• Masukkan background job ke antrean alih-alih menjalankannya sekaligus.
• Stream response yang panjang: satu request yang di-stream dihitung sebagai satu request.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api14.com/api/v1", api_key="sk-api14-...", max_retries=0)

for attempt in range(5):
    try:
        r = client.chat.completions.create(model="openai/gpt-5-mini", messages=[{"role": "user", "content": "Hi"}])
        break
    except RateLimitError as e:
        if e.code == "daily_limit_reached":
            raise
        time.sleep(int(e.response.headers.get("retry-after", 2 ** attempt)))

Lihat Error untuk semua kode status.