> Yapay zeka ajanları için: adım adım kurulum kılavuzu — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), dokümantasyon dizini — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Hatalar ve limitler

Gateway'in istek limitleri, zaman aşımları ve hata kodları. Her yanıt için ne zaman oluştuğu ve ne yapılması gerektiği belirtilir: isteği tekrarlayın veya düzeltin.

## Limitler

Sayılar `GET /v1/capabilities` yanıtının `limits` alanından gelir: orada her zaman güncel değerler bulunur.

| Limit | Değer | Aşıldığında |
| --- | --- | --- |
| Anahtar başına dakikadaki istek sayısı | 120, ilk istekten itibaren 60 sn'lik pencere | `429 rate_limit_exceeded` ve `Retry-After` başlığı; ağ geçidinin 5xx redleri kotadan düşmez |
| Hesabın eşzamanlı istekleri | sınırlıdır | fazlalar kuyrukta bekler; bekleyemeyenler — `429 queue_timeout` |
| İstek gövdesinin boyutu | 16 MiB | `413` |
| Yanıt uzunluğu | [modellere göre — aşağıdaki tablo](https://gate.joingonka.ai/tr/docs/errors#max-tokens) | modelin üst sınırından büyükse — hata vermeden üst sınıra kırpılır |
| Alt anahtarlar | yönetim anahtarı başına 50'e kadar, her birine dakikada 120 istek | üst sınırları yükseltmek — destek üzerinden |

### Modellere göre yanıt uzunluğu

`max_tokens` olmadan ağ geçidi varsayılanı atar: stream'siz — yanıtın zaman aşımlarına sığması için daha kısa, stream'de — modelin üst sınırı. `max_completion_tokens` — aynı alan.

| `model` | Üst sınır | Stream'siz | Stream'de |
| --- | ---: | ---: | ---: |
| `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 |

## Zaman aşımları

| Aşama | Değer | Ne olur |
| --- | --- | --- |
| Kuyrukta yer bekleme | 45 sn | `Retry-After: 1` başlığıyla `429 queue_timeout` |
| Ağın yanıtının başlaması, stream | 150 sn | `504 upstream_timeout`; giriş token'larının tahmini tutarı tahsil edilir |
| Ağın yanıtının başlaması, stream'siz | 150 sn | `504 upstream_timeout`; giriş token'larının tahmini tutarı tahsil edilir |
| Yanıt üretimi | ≈ 300 sn | ağ üretimi keser: yanıt `finish_reason: length` ile gelir — bir sonraki istekle devam edin |
| Stream chunk'ları arasındaki duraklama | 30 sn | akış kapanır: `joingonka-stream-stalled` chunk'ında `finish_reason: stop` |
| Stream'de etkinlik sinyali | 15 sn | `: keep-alive` yorumu — SSE istemcileri bunu atlar |
| Akışın açılması | 30 sn | bu ana kadar ret yanıt koduyla, sonrasında `joingonka-error` chunk'ıyla gelir |
| Stream'siz erken yanıt | 90 sn | ağ geçidi `200` verir ve her 15 sn saniyede bir boşluk gönderir — JSON geçerliliğini korur; bundan sonraki bir hata gövdede `error` alanıyla gelir, durum `200` olarak kalır |

> **Zaman aşımında neler tahsil edilir**
>
> Ağ tarafından kabul edilen bir istek iptal edilemez. `504 upstream_timeout` durumunda giriş tokenlarının tahmini ücretlendirilir, çıkış tokenları ücretlendirilmez; tekrar deneme yeni bir ücretlendirmedir. Nihai `usage` öncesinde kesilen bir akış da aynı şekilde faturalandırılır. Uzun yanıtları `stream: true` ile isteyin.

## Hata kodları

Hata gövdesi, `message, type, code, param` alanlarını içeren bir `error` nesnesidir; bazı alanlar her hatada bulunmaz. Durum koduna ve `type` alanına göre hareket edin, `code` ile netleştirin: `message` metni değişebilir. Anthropic formatı [Anthropic hata formatı](https://gate.joingonka.ai/tr/docs/errors#anthropic-errors) bölümünde.

```json
{
  "error": {
    "message": "Model is currently overloaded in the Gonka network",
    "type": "rate_limit_exceeded",
    "code": "upstream_rate_limited"
  }
}
```

| Yanıt | Ne zaman | Ne yapmalı |
| --- | --- | --- |
| 400 `invalid_request_error` | Geçersiz gövde: `messages` yok, mesaj nesne değil, gövde JSON değil; bilinmeyen model — `param` ile birlikte: `model` ve metinde mevcut modellerin listesi | İsteği hata metnine göre düzeltin |
| 400 `invalid_request_error` `empty_content_after_normalization` | Mesaj normalleştirmeden sonra boş — örneğin yalnızca bir görsel içeriyordu | Mesaja metin ekleyin |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Aynı istekte `web` ve `privacy-sanitization` eklentileri | Yalnızca birini bırakın |
| 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: kayıtlı bir yanıta, diyaloğa veya öğeye referans; arka plan modu; yerleşik araç gereksinimi | Geçmişi tamamen `input` içinde gönderin |
| 400 `api_error` | Ağ parametreleri reddetti — örneğin `reasoning_effort` değeri ağın listesinin dışında | Değeri hata metnine göre düzeltin |
| 401 `authentication_error` | Anahtar bulunamadı, iptal edildi veya formatı bilinmiyor | Anahtarı [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) sayfasından kontrol edin |
| 402 `insufficient_funds` | Bakiye, isteğin tahminini karşılamıyor; kalan tutar `balance_ngonka` içinde | Bakiyenizi yükleyin: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Anahtarsız istek, site dışından (`is_demo: true`) | Bir API anahtarı iletin |
| 402 `child_key_limit_exceeded` | Anahtarın harcama limiti aşıldı — günlük, aylık veya toplam; kalan tutarlar `daily_remaining, monthly_remaining, total_remaining` içinde | Anahtarın limitini [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) sayfasından yükseltin veya sıfırlanmasını bekleyin |
| 403 `forbidden` | Modele yapılan istekte yönetici anahtarı `gm-`; yalnızca panele özel rotada API anahtarı | İstekler için — `jg-` veya `gc-` anahtarı; hesap yönetimi — panelde |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: model katalogda yok veya geçici olarak gizli | id'yi `GET /v1/models` içinden alın |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` ve diğer durum adresleri, `/v1/responses/compact` | Geçmişi kendiniz saklayın; Codex CLI için kendi sağlayıcı id'nizi tanımlayın |
| 404 `invalid_request_error` | Bilinmeyen yol | Metodu, yolu ve temel adresi kontrol edin |
| 413 `invalid_request_error` | İstek gövdesi limiti aşıyor | İsteği kısaltın |
| 415 `invalid_request_error` | Gövde, başlığa göre JSON değil: `Content-Type: application/json` gerekli | `Content-Type: application/json` gönderin |
| 429 `rate_limit_exceeded` | Anahtar başına dakikadaki istek sayısı aşıldı; gövdede — `limit, remaining, reset` içeren `rate_limit` | `Retry-After` içinde belirtilen saniye kadar bekleyin |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Model Gonka ağında aşırı yüklü | `Retry-After` sonrasında tekrar deneyin veya başka bir model alın — [Modeller](https://gate.joingonka.ai/tr/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Ağdaki tüm yerler dolu: kuyruk dolu veya bekleme süresi doldu | `Retry-After` sonrasında tekrar deneyin |
| 500 `server_error` | Gateway iç hatası | Daha sonra tekrar deneyin; tekrarlanırsa desteğe yazın ve `x-request-id` ekleyin |
| 501 `not_implemented` | `POST /v1/embeddings`: ağda embedding modeli yok | Başka bir embedding hizmeti kullanın |
| 502 `api_error` `upstream_unauthorized` | Ağ sağlayıcısı gateway'in kimlik bilgilerini reddetti — sizin anahtarınız sorunsuz | Bir dakika sonra tekrar deneyin |
| 502 `api_error` | Gonka ağı hatası; `code` — ağ gönderdiyse ağdan gelir | Ara vererek tekrar deneyin veya başka bir model alın |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | Model şu anda ağ denemelerine göre kullanılamıyor: arıza, başlatma, kararsızlık veya kimse onu işletmiyor; beklemeden anında reddedilir | Başka bir model alın — hata metni hangisi olduğunu söyler; liste — [Modeller](https://gate.joingonka.ai/tr/docs/models) |
| 503 `service_unavailable` | Kullanılabilir node yok | Daha sonra tekrar deneyin |
| 504 `timeout` `upstream_timeout` | Ağ isteği kabul etti ama zamanında yanıt vermedi; giriş tokenlarının tahmini ücretlendirildi | Uzun yanıtlar için — `stream: true`; tekrar deneme yeni bir ücretlendirmedir |

## Açık akıştaki hatalar

Akış açılana kadar ret, normal yanıt koduyla gelir — akışsız gibi. Açıldıktan sonra durum artık `200` olur ve hata şöyle gelir:

- Chat Completions — `error` alanlı `joingonka-error` parçası, ardından `[DONE]` olmadan kopma.
- Erken yanıttan sonra akışsız — durum `200` ve `error` alanlı gövde.
- Anthropic Messages — `event: error` olayı, ardından akış kapanır.
- OpenAI Responses — `response.failed` olayı, neden `response.error.code` içinde.
- Legacy Completions — `data: {"error": …}`, ardından `[DONE]`.

```text
data: {"id":"joingonka-error","object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"error":{"message":"Gonka network error","type":"api_error"}}
```

## Anthropic hata formatı

- `POST /v1/messages`, Anthropic zarfıyla yanıt verir: `{"type": "error", "error": {"type", "message"}}`.
- Gateway retleri yukarıdaki tablodaki `type` alanını korur (`insufficient_funds`, `model_unavailable` ve diğerleri); bu zarfta `code` alanı yok — neden metinde.
- İstek biçimi hataları — `invalid_request_error`: mesaj yok veya `max_tokens`, adsız araç çağrısı, bilinmeyen model.
- Bilinmeyen yol — `not_found_error`, çok büyük gövde — `request_too_large`.

```text
event: error
data: {"type":"error","error":{"type":"timeout","message":"Upstream timeout"}}
```

## Ne tekrarlanmalı

- `Retry-After` içindeki aradan sonra: `429`
- Artan arayla — 1, 2, 4 sn ve devamı: `500`, `502`, `503 service_unavailable`, `504`
- Başka bir modelle: `503 model_unavailable`
- Değişiklik yapmadan tekrarlamayın — isteği, anahtarı veya bakiyeyi düzeltin: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

`504` sonrasındaki her tekrar, giriş tahmininin yeni bir ücretlendirmesidir; uzun yanıtlar için `stream: true` açın.

Hata tekrarlanıyor — desteğe yazın ve yanıt başlıklarındaki `x-request-id` alanını ekleyin.