> Untuk agen AI: panduan pengaturan langkah demi langkah — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), indeks dokumentasi — [`/llms.txt`](https://gate.joingonka.ai/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](https://gate.joingonka.ai/id/docs/errors#max-tokens) | 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](https://gate.joingonka.ai/id/docs/errors#anthropic-errors).

```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](https://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](https://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](https://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](https://gate.joingonka.ai/id/docs/models) |
| 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](https://gate.joingonka.ai/id/docs/models) |
| 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-error` dengan field `error`, lalu terputus tanpa `[DONE]`.
- Tanpa streaming setelah respons awal — status `200` dan body dengan field `error`.
- Anthropic Messages — event `event: error`, lalu stream ditutup.
- OpenAI Responses — event `response.failed`, penyebabnya di `response.error.code`.
- Legacy Completions — `data: {"error": …}`, lalu `[DONE]`.

```text
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/messages` merespons dengan envelope Anthropic: `{"type": "error", "error": {"type", "message"}}`.
- Penolakan gateway mempertahankan `type` dari tabel di atas (`insufficient_funds`, `model_unavailable`, dan lainnya); field `code` tidak ada di envelope ini — penyebabnya ada di teks.
- Error bentuk permintaan — `invalid_request_error`: tidak ada messages atau `max_tokens`, pemanggilan tool tanpa nama, model tidak dikenal.
- Path tidak dikenal — `not_found_error`, body terlalu besar — `request_too_large`.

```text
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.