Untuk agen AI: panduan pengaturan langkah demi langkah — /docs/agents.md, indeks dokumentasi — /llms.txt.
Error dan batasan
Batas permintaan, timeout, dan kode error gateway. Untuk setiap respons dijelaskan kapan terjadi dan apa yang harus dilakukan: ulangi permintaan atau perbaiki.
Batasan#
Angka-angka diambil dari field limits pada respons GET /v1/capabilities: nilainya selalu terbaru di sana.
| Batas | Nilai | Jika terlampaui |
|---|---|---|
| Permintaan per menit per kunci | 120, jendela 60 dtk sejak permintaan pertama | 429 rate_limit_exceeded dan header Retry-After; penolakan 5xx dari gateway tidak memakai kuota |
| Permintaan simultan akun | dibatasi | kelebihan menunggu dalam antrean; jika tidak terpenuhi — 429 queue_timeout |
| Ukuran body permintaan | 16 MiB | 413 |
| Panjang respons | per model — tabel di bawah | melebihi plafon model — dipotong ke plafon, tanpa error |
| Kunci anak | hingga 50 per kunci pengelola, masing-masing hingga 120 permintaan per menit | untuk menaikkan plafon — melalui dukungan |
Panjang respons per model#
Tanpa max_tokens, gateway mengisi default: tanpa streaming — lebih pendek agar respons muat dalam timeout; dalam streaming — plafon model. max_completion_tokens — field yang sama.
model | Plafon | Tanpa streaming | Dalam streaming |
|---|---|---|---|
MiniMaxAI/MiniMax-M2.7 | 8192 | 1500 | 8192 |
deepseek-ai/DeepSeek-V4-Flash-0731 | 32768 | 1500 | 32768 |
zai-org/GLM-5.3-Flash | 8192 | 3000 | 8192 |
Timeout#
| Tahap | Nilai | Yang terjadi |
|---|---|---|
| Menunggu tempat dalam antrean | 45 dtk | 429 queue_timeout dengan header Retry-After: 1 |
| Awal respons jaringan, streaming | 150 dtk | 504 upstream_timeout; estimasi token input akan didebit |
| Awal respons jaringan, tanpa streaming | 150 dtk | 504 upstream_timeout; estimasi token input akan didebit |
| Generasi respons | ≈ 300 dtk | jaringan memutus generasi: respons datang dengan finish_reason: length — lanjutkan dengan permintaan berikutnya |
| Jeda antar chunk streaming | 30 dtk | stream ditutup: finish_reason: stop di chunk joingonka-stream-stalled |
| Sinyal aktivitas dalam streaming | 15 dtk | komentar : keep-alive — klien SSE akan melewatinya |
| Pembukaan stream | 30 dtk | sebelum waktu ini penolakan datang dengan kode respons, setelahnya — lewat chunk joingonka-error |
| Respons awal tanpa streaming | 90 dtk | gateway mengirim 200 dan setiap 15 dtk mengirim spasi — JSON tetap valid; error setelah itu datang di body dengan field error, status tetap 200 |
Apa yang didebit saat timeout
Permintaan yang sudah diterima jaringan tidak bisa dibatalkan. Pada 504 upstream_timeout, estimasi token input tetap ditagih, token output tidak; percobaan ulang berarti penagihan baru. Stream yang terputus sebelum usage final juga ditagih sama. Untuk jawaban panjang, gunakan stream: true.
Kode error#
Body error berupa objek error dengan field message, type, code, param; tidak semua error memiliki semua field. Berpatokan pada status dan type, periksa lewat code: teks message bisa berubah. Format Anthropic ada di bagian Format error Anthropic.
JSON
{
"error": {
"message": "Model is currently overloaded in the Gonka network",
"type": "rate_limit_exceeded",
"code": "upstream_rate_limited"
}
}| Respons | Kapan | Yang harus dilakukan |
|---|---|---|
400 invalid_request_error | Body tidak valid: messages tidak ada, message bukan objek, body bukan JSON; model tidak dikenal — dengan param: model dan daftar model yang tersedia di teks | Perbaiki permintaan sesuai teks error |
400 invalid_request_error empty_content_after_normalization | Message kosong setelah normalisasi — misalnya hanya berisi gambar | Tambahkan teks pada message |
400 invalid_request_error web_search_privacy_sanitization_not_supported | Plugin web dan privacy-sanitization dalam satu permintaan | Pilih salah satu saja |
400 invalid_request_error previous_response_id_not_supported conversation_not_supported item_reference_not_supported background_not_supported hosted_tool_choice_not_supported | OpenAI Responses: referensi ke respons, dialog, atau elemen tersimpan; mode background; syarat tool bawaan | Kirim seluruh riwayat di input |
400 api_error | Jaringan menolak parameter — misalnya nilai reasoning_effort di luar daftarnya | Perbaiki nilainya sesuai teks error |
401 authentication_error | Kunci tidak ditemukan, dicabut, atau formatnya tidak dikenal | Periksa kunci di halaman gate.joingonka.ai/keys |
402 insufficient_funds | Saldo tidak cukup untuk estimasi permintaan; sisanya ada di balance_ngonka | Isi ulang saldo: gate.joingonka.ai/billing |
402 insufficient_funds | Permintaan tanpa kunci bukan dari situs (is_demo: true) | Sertakan kunci API |
402 child_key_limit_exceeded | Batas pengeluaran kunci terlampaui — harian, bulanan, atau total; sisanya ada di daily_remaining, monthly_remaining, total_remaining | Naikkan batas kunci di halaman gate.joingonka.ai/keys atau tunggu reset |
403 forbidden | Kunci pengelola gm- pada permintaan ke model; kunci API pada rute khusus dashboard | Untuk permintaan — kunci jg- atau gc-; pengelolaan akun dilakukan di dashboard |
404 invalid_request_error model_not_found | GET /v1/models/{model}: model tidak ada di katalog atau sedang disembunyikan sementara | Ambil id dari GET /v1/models |
404 invalid_request_error not_found compact_not_supported | OpenAI Responses: /v1/responses/{id} dan alamat state lainnya, /v1/responses/compact | Simpan riwayat di sisi Anda; untuk Codex CLI, atur id provider sendiri |
404 invalid_request_error | Path tidak dikenal | Periksa method, path, dan alamat dasar |
413 invalid_request_error | Body permintaan melebihi batas | Pangkas permintaan |
415 invalid_request_error | Body bukan JSON menurut header: perlu Content-Type: application/json | Kirim Content-Type: application/json |
429 rate_limit_exceeded | Jumlah permintaan per menit per kunci terlampaui; di body ada rate_limit dengan limit, remaining, reset | Tunggu sebanyak detik yang tertera di Retry-After |
429 rate_limit_exceeded upstream_rate_limited | Model kelebihan beban di jaringan Gonka | Coba lagi setelah Retry-After atau pakai model lain — Model |
429 rate_limit_exceeded queue_timeout queue_full | Semua slot ke jaringan penuh: antrean penuh atau waktu tunggu habis | Coba lagi setelah Retry-After |
500 server_error | Error internal gateway | Coba lagi nanti; jika berulang, hubungi dukungan dan sertakan x-request-id |
501 not_implemented | POST /v1/embeddings: tidak ada model embedding di jaringan | Gunakan layanan embedding lain |
502 api_error upstream_unauthorized | Provider jaringan menolak kredensial gateway — kunci Anda baik-baik saja | Coba lagi dalam satu menit |
502 api_error | Error jaringan Gonka; code berasal dari jaringan, jika dikirim | Coba lagi dengan jeda atau pakai model lain |
503 model_unavailable model_outage model_initializing model_unstable model_not_served | Model sedang tidak tersedia menurut probe jaringan: gangguan, sedang start, tidak stabil, atau tidak ada yang melayaninya; langsung ditolak, tanpa menunggu | Pakai model lain — teks error akan memberi petunjuk; daftarnya di Model |
503 service_unavailable | Tidak ada node yang tersedia | Coba lagi nanti |
504 timeout upstream_timeout | Jaringan menerima permintaan tetapi tidak menjawab tepat waktu; estimasi token input sudah ditagih | Untuk jawaban panjang — stream: true; percobaan ulang berarti penagihan baru |
Error pada stream yang terbuka#
Selama stream belum dibuka, penolakan datang dengan kode respons biasa — seperti tanpa streaming. Setelah dibuka, statusnya sudah 200, dan error datang seperti ini:
- Chat Completions — chunk
joingonka-errordengan fielderror, lalu terputus tanpa[DONE]. - Tanpa streaming setelah respons awal — status
200dan body dengan fielderror. - Anthropic Messages — event
event: error, lalu stream ditutup. - OpenAI Responses — event
response.failed, penyebabnya diresponse.error.code. - Legacy Completions —
data: {"error": …}, lalu[DONE].
SSE
data: {"id":"joingonka-error","object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"error":{"message":"Gonka network error","type":"api_error"}}Format error Anthropic#
POST /v1/messagesmerespons dengan envelope Anthropic:{"type": "error", "error": {"type", "message"}}.- Penolakan gateway mempertahankan
typedari tabel di atas (insufficient_funds,model_unavailable, dan lainnya); fieldcodetidak ada di envelope ini — penyebabnya ada di teks. - Error bentuk permintaan —
invalid_request_error: tidak ada messages ataumax_tokens, pemanggilan tool tanpa nama, model tidak dikenal. - Path tidak dikenal —
not_found_error, body terlalu besar —request_too_large.
SSE
event: error
data: {"type":"error","error":{"type":"timeout","message":"Upstream timeout"}}Apa yang perlu diulang#
- Setelah jeda dari
Retry-After:429 - Dengan jeda bertambah — 1, 2, 4 detik dan seterusnya:
500,502,503 service_unavailable,504 - Dengan model lain:
503 model_unavailable - Jangan ulangi tanpa perubahan — perbaiki permintaan, kunci, atau saldo:
400,401,402,403,404,413,415,501
Setiap pengulangan setelah 504 berarti penagihan baru atas estimasi input; untuk jawaban panjang aktifkan stream: true.
Jika error berulang, hubungi dukungan dan sertakan x-request-id dari header respons.