> Para sa mga AI agent: step-by-step na gabay sa setup — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), index ng dokumentasyon — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Mga error at limitasyon

Mga limitasyon sa request, timeout, at error code ng gateway. Para sa bawat response, sinasabi kung kailan ito nangyayari at ano ang gagawin: ulitin ang request o ayusin ito.

## Mga limitasyon

Ang mga numero — mula sa field na `limits` ng sagot na `GET /v1/capabilities`: doon ay laging may aktwal na mga halaga.

| Limitasyon | Halaga | Kapag lumampas |
| --- | --- | --- |
| Mga request kada minuto bawat key | 120, window na 60 s mula sa unang request | `429 rate_limit_exceeded` at header na `Retry-After`; ang mga pagtanggi ng gateway na 5xx ay hindi gumagamit ng quota |
| Mga sabay-sabay na request ng account | limitado | ang mga sobra ay naghihintay sa pila; kung hindi nakapaghintay — `429 queue_timeout` |
| Laki ng body ng request | 16 MiB | `413` |
| Haba ng sagot | [ayon sa modelo — talahanayan sa ibaba](https://gate.joingonka.ai/tl/docs/errors#max-tokens) | higit sa kisame ng modelo — pinuputol hanggang sa kisame, walang error |
| Mga child key | hanggang 50 bawat management key, hanggang 120 request kada minuto sa bawat isa | itaas ang mga kisame — sa pamamagitan ng support |

### Haba ng sagot ayon sa modelo

Kung walang `max_tokens`, naglalagay ang gateway ng default: walang stream — mas maikli, upang ang sagot ay umangkop sa mga timeout, sa stream — ang kisame ng modelo. Ang `max_completion_tokens` — parehong field.

| `model` | Kisame | Walang stream | Sa stream |
| --- | ---: | ---: | ---: |
| `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 |

## Mga timeout

| Yugto | Halaga | Ano ang nangyayari |
| --- | --- | --- |
| Paghihintay ng puwesto sa pila | 45 s | `429 queue_timeout` na may header na `Retry-After: 1` |
| Simula ng sagot ng network, stream | 150 s | `504 upstream_timeout`; ibabawas ang pagtatantya ng input tokens |
| Simula ng sagot ng network, walang stream | 150 s | `504 upstream_timeout`; ibabawas ang pagtatantya ng input tokens |
| Pagbuo ng sagot | ≈ 300 s | pinutol ng network ang pagbuo: ang sagot ay dumarating na may `finish_reason: length` — ipagpatuloy sa susunod na request |
| Pahinga sa pagitan ng mga chunk ng stream | 30 s | nagsasara ang stream: `finish_reason: stop` sa chunk na `joingonka-stream-stalled` |
| Signal ng aktibidad sa stream | 15 s | comment na `: keep-alive` — nilalaktawan ito ng mga SSE client |
| Pagbukas ng stream | 30 s | hanggang sa sandaling ito, ang pagtanggi ay dumarating bilang response code, pagkatapos — bilang chunk na `joingonka-error` |
| Maagang sagot na walang stream | 90 s | ibinibigay ng gateway ang `200` at bawat 15 s ay nagpapadala ng mga space — nananatiling valid ang JSON; ang error pagkatapos nito ay dumarating sa body na may field na `error`, ang status ay nananatiling `200` |

> **Ano ang ibinabawas sa timeout**
>
> Ang kahilingang tinanggap ng network ay hindi na maaaring kanselahin. Sa `504 upstream_timeout`, ang pagtatantya ng input tokens ay sisingilin, ang output ay hindi; ang muling pagsubok ay bagong singil. Ang stream na naputol bago ang huling `usage` ay sisingilin din nang pareho. Para sa mahahabang sagot, gamitin ang `stream: true`.

## Mga error code

Ang katawan ng error ay isang object na `error` na may mga field na `message, type, code, param`; hindi lahat ng error ay may lahat ng field. Batayan ang status at `type`, tingnan ang `code` para sa detalye: ang teksto ng `message` ay maaaring magbago. Ang format ng Anthropic ay nasa seksyong [Format ng error ng Anthropic](https://gate.joingonka.ai/tl/docs/errors#anthropic-errors).

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

| Sagot | Kailan | Ano ang gagawin |
| --- | --- | --- |
| 400 `invalid_request_error` | Maling katawan: walang `messages`, ang mensahe ay hindi object, ang katawan ay hindi JSON; hindi kilalang modelo — kasama ng `param`: `model` at listahan ng mga available na modelo sa teksto | Itama ang kahilingan ayon sa teksto ng error |
| 400 `invalid_request_error` `empty_content_after_normalization` | Walang laman ang mensahe pagkatapos ng normalisasyon — halimbawa, larawan lang ang nilalaman nito | Magdagdag ng teksto sa mensahe |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Ang mga plugin na `web` at `privacy-sanitization` ay nasa isang kahilingan | Iwanan ang isa sa kanila |
| 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: reference sa naka-save na sagot, diyalogo o item; background mode; pangangailangan ng built-in na tool | Ipadala ang buong kasaysayan sa `input` |
| 400 `api_error` | Tinanggihan ng network ang mga parameter — halimbawa, ang halaga ng `reasoning_effort` ay wala sa listahan nito | Itama ang halaga ayon sa teksto ng error |
| 401 `authentication_error` | Hindi mahanap ang key, na-revoke, o hindi kilalang format | Suriin ang key sa pahina ng [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | Kulang ang balanse para sa pagtatantya ng kahilingan; ang natitira ay nasa `balance_ngonka` | Mag-top up ng balanse: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Kahilingang walang key na hindi galing sa site (`is_demo: true`) | Magpasa ng API key |
| 402 `child_key_limit_exceeded` | Lumampas sa limitasyon ng gastos ng key — arawan, buwanan o kabuuan; ang natitira ay nasa `daily_remaining, monthly_remaining, total_remaining` | Itaas ang limitasyon ng key sa pahina ng [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) o hintayin ang pag-reset |
| 403 `forbidden` | Ang management key na `gm-` ay nasa kahilingan sa modelo; ang API key sa ruta ay para sa dashboard lamang | Para sa mga kahilingan — key na `jg-` o `gc-`; pamamahala ng account — sa dashboard |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: wala ang modelo sa catalog o pansamantalang nakatago | Kunin ang id mula sa `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` at iba pang address ng state, `/v1/responses/compact` | Itago ang kasaysayan sa iyong panig; para sa Codex CLI, itakda ang sariling provider id |
| 404 `invalid_request_error` | Hindi kilalang path | Suriin ang method, path at base address |
| 413 `invalid_request_error` | Lumampas sa limitasyon ang katawan ng kahilingan | Paikliin ang kahilingan |
| 415 `invalid_request_error` | Ang katawan ay hindi JSON ayon sa header: kailangan ang `Content-Type: application/json` | Ipadala ang `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | Lumampas sa bilang ng kahilingan kada minuto bawat key; sa katawan — `rate_limit` na may `limit, remaining, reset` | Maghintay ng ilang segundo ayon sa `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Sobrang load ang modelo sa network ng Gonka | Ulitin pagkatapos ng `Retry-After` o pumili ng ibang modelo — [Mga Modelo](https://gate.joingonka.ai/tl/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Puno na ang lahat ng slot sa network: puno ang pila o nag-expire ang paghihintay | Ulitin pagkatapos ng `Retry-After` |
| 500 `server_error` | Panloob na error ng gateway | Ulitin mamaya; kung paulit-ulit — sumulat sa support at isama ang `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings`: walang embedding models sa network | Gumamit ng ibang embedding service |
| 502 `api_error` `upstream_unauthorized` | Tinanggihan ng provider ng network ang credentials ng gateway — maayos ang iyong key | Ulitin pagkalipas ng isang minuto |
| 502 `api_error` | Error sa network ng Gonka; ang `code` ay galing sa network, kung ipinadala nito | Ulitin na may pause o pumili ng ibang modelo |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | Hindi available ang modelo ngayon ayon sa mga probe ng network: pagkasira, pagsisimula, kawalang-tatag o walang nagse-serve nito; agad na pagtanggi, walang paghihintay | Pumili ng ibang modelo — sasabihin ng teksto ng error kung alin; ang listahan — [Mga Modelo](https://gate.joingonka.ai/tl/docs/models) |
| 503 `service_unavailable` | Walang available na node | Ulitin mamaya |
| 504 `timeout` `upstream_timeout` | Tinanggap ng network ang kahilingan pero hindi sumagot sa oras; ang pagtatantya ng input tokens ay siningil | Para sa mahahabang sagot — `stream: true`; ang muling pagsubok — bagong singil |

## Mga error sa bukas na stream

Hangga't hindi pa bukas ang stream, dumarating ang pagtanggi sa karaniwang response code — tulad ng walang stream. Pagkatapos ng pagbukas, ang status ay `200`, at ganito dumarating ang error:

- Chat Completions — chunk na `joingonka-error` na may field na `error`, tapos putol na walang `[DONE]`.
- Walang stream pagkatapos ng maagang sagot — status na `200` at katawan na may field na `error`.
- Anthropic Messages — event na `event: error`, tapos nagsasara ang stream.
- OpenAI Responses — event na `response.failed`, ang dahilan ay nasa `response.error.code`.
- Legacy Completions — `data: {"error": …}`, tapos `[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 ng error ng Anthropic

- Ang `POST /v1/messages` ay sumasagot ng envelope ng Anthropic: `{"type": "error", "error": {"type", "message"}}`.
- Pinapanatili ng mga pagtanggi ng gateway ang `type` mula sa talahanayan sa itaas (`insufficient_funds`, `model_unavailable` at iba pa); walang field na `code` sa envelope na ito — nasa teksto ang dahilan.
- Mga error sa form ng kahilingan — `invalid_request_error`: walang mensahe o `max_tokens`, tool call na walang pangalan, hindi kilalang modelo.
- Hindi kilalang path — `not_found_error`, masyadong malaking katawan — `request_too_large`.

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

## Ano ang dapat ulitin

- Pagkatapos ng pause mula sa `Retry-After`: `429`
- May tumataas na pause — 1, 2, 4 s at higit pa: `500`, `502`, `503 service_unavailable`, `504`
- Sa ibang modelo: `503 model_unavailable`
- Huwag ulitin nang walang pagbabago — itama ang kahilingan, key o balanse: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

Bawat muling pagsubok pagkatapos ng `504` ay bagong singil sa pagtatantya ng input; para sa mahahabang sagot, i-on ang `stream: true`.

Kung paulit-ulit ang error — sumulat sa support at isama ang `x-request-id` mula sa headers ng response.