Lewati ke konten
SatupodSatupodPanduan Satupod

Error & batas laju

Format error

Section titled “Format error”

Semua endpoint kecuali /v1/messages memakai amplop OpenAI:

{
  "error": {
    "message": "LLM_FREE_QUOTA_EXHAUSTED",
    "type": "rate_limit_error",
    "code": "LLM_FREE_QUOTA_EXHAUSTED"
  }
}
  • code stabil dan aman untuk dicocokkan di kode Anda.
  • message bisa berisi penjelasan yang lebih panjang, misalnya field yang salah atau pesan penolakan dari provider. Jangan mencocokkan teksnya.
  • type: authentication_error (401), rate_limit_error (429), server_error (5xx), atau invalid_request_error (lainnya).

/v1/messages memakai amplop Anthropic. Lihat Messages.

Kode error

Section titled “Kode error”

400 — permintaan tidak bisa diproses

Section titled “400 — permintaan tidak bisa diproses”
Kode Arti
LLM_REQUEST_INVALID Bentuk permintaan salah. message menyebut field-nya.
LLM_OUTPUT_LIMIT max_tokens melebihi batas platform.
LLM_CHAT_UNSUPPORTED Model ini bukan model chat.
LLM_TOOLS_UNSUPPORTED Tools dikirim ke endpoint atau model yang tidak mendukungnya.
LLM_STRUCTURED_COUNT_UNSUPPORTED json_schema dikirim ke model tanpa structured output. json_object tetap bisa.
LLM_EMBEDDINGS_UNSUPPORTED, LLM_IMAGES_UNSUPPORTED, LLM_SPEECH_UNSUPPORTED, LLM_TRANSCRIPTION_UNSUPPORTED, LLM_VIDEO_UNSUPPORTED Model ini tidak punya fitur untuk endpoint tersebut.
LLM_UNIT_NOT_PRICED Ukuran atau kualitas itu tidak dijual. Pilih yang tercantum di katalog.

401 — kunci tidak diterima

Section titled “401 — kunci tidak diterima”
Kode Arti
INVALID_API_KEY Kunci salah, tidak ada, atau sudah dicabut.
KEY_EXPIRED Kunci melewati tanggal kedaluwarsanya.

402 — saldo

Section titled “402 — saldo”
Kode Arti
INSUFFICIENT_CREDIT Kredit AI tidak cukup. Beli Kredit AI.

403 — tidak diizinkan

Section titled “403 — tidak diizinkan”
Kode Arti
MODEL_NOT_ALLOWED Kunci ini tidak diizinkan memakai model tersebut.
KEY_SPEND_CAP_EXCEEDED Batas bulanan atau batas lifetime kunci tercapai.
CUSTOMER_NOT_ACTIVE Akun tidak aktif. Hubungi bantuan.

404, 409, 410, 413

Section titled “404, 409, 410, 413”
Status Kode Arti
404 MODEL_NOT_FOUND Nama model salah, atau di luar izin kunci.
404 VIDEO_NOT_FOUND ID pekerjaan video tidak ada, atau milik akun lain.
409 VIDEO_NOT_READY Video belum selesai. Baca statusnya dulu.
409 VIDEO_GENERATION_FAILED Pembuatan video gagal. Kreditnya dikembalikan.
410 VIDEO_EXPIRED Berkas video sudah dihapus provider.
413 LLM_AUDIO_TOO_LARGE Berkas audio di atas 25 MB.
413 — Body di atas 128 MB.

429 — terlalu banyak

Section titled “429 — terlalu banyak”
Kode Arti retry-after
LLM_RATE_LIMITED Batas permintaan per menit akun tercapai. Ada
LLM_CONCURRENCY_LIMIT Terlalu banyak permintaan berjalan bersamaan (20 per akun). Tidak ada; tunggu salah satu selesai
LLM_FREE_RATE_LIMITED Lebih dari 20 permintaan model gratis per menit. Ada
LLM_FREE_QUOTA_EXHAUSTED Jatah harian model gratis habis. Kembali pukul 00.00 WIB. Tidak ada

5xx — masalah di sisi Satupod atau provider

Section titled “5xx — masalah di sisi Satupod atau provider”
Status Kode Arti
502 LLM_RESPONSE_INVALID, LLM_STREAM_*, LLM_USAGE_NOT_BILLED Jawaban provider tidak bisa diterima atau tidak bisa ditagih dengan benar, jadi tidak diteruskan.
503 LLM_REQUEST_FAILED Provider tidak bisa dihubungi.

Error 5xx aman diulang setelah jeda singkat.

Header rate limit

Section titled “Header rate limit”

Setiap jawaban yang melewati pemeriksaan batas laju membawa header berikut, termasuk jawaban yang berhasil:

Header Isi
x-ratelimit-limit-requests Batas permintaan per menit untuk akun Anda
x-ratelimit-remaining-requests Sisa permintaan dalam menit berjalan
x-ratelimit-reset-requests Kapan menit berjalan berakhir, misalnya 23s
retry-after Pada 429: berapa detik harus menunggu

Batasnya dihitung per akun, bukan per kunci. Membuat kunci baru tidak menambah kuota.

Batas per menit akun sengaja dibuat jauh di atas pemakaian wajar. Fungsinya menghentikan loop yang lepas kendali, bukan membatasi pemakaian normal.

Mengulang permintaan dengan aman

Section titled “Mengulang permintaan dengan aman”
  • 429 dengan retry-after: tunggu sesuai header, lalu ulang.
  • 429 tanpa retry-after: untuk LLM_CONCURRENCY_LIMIT, kurangi paralelisme. Untuk LLM_FREE_QUOTA_EXHAUSTED, jangan diulang sampai 00.00 WIB.
  • 5xx: ulang dengan jeda yang makin panjang (exponential backoff).
  • Stream terputus (LLM_STREAM_UNCERTAIN): bagian yang sudah dihasilkan tetap ditagih. Periksa AI → Pemakaian sebelum mengulang.
  • 4xx lainnya: jangan diulang tanpa memperbaiki permintaannya.