> สำหรับเอเจนต์ AI: คำแนะนำการตั้งค่าทีละขั้นตอน — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), ดัชนีเอกสาร — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# ข้อผิดพลาดและลิมิต

ขีดจำกัดคำขอ ไทม์เอาต์ และรหัสข้อผิดพลาดของเกตเวย์ สำหรับแต่ละ réponse จะระบุว่าเกิดขึ้นเมื่อใดและควรทำอย่างไร: ส่งคำขอซ้ำหรือแก้ไขคำขอ

## ลิมิต

ตัวเลขมาจากฟิลด์ `limits` ของการตอบกลับ `GET /v1/capabilities`: ที่นั่นมีค่าที่เป็นปัจจุบันเสมอ

| ลิมิต | ค่า | เมื่อเกิน |
| --- | --- | --- |
| คำขอต่อนาทีต่อคีย์ | 120, หน้าต่าง 60 วิ นับจากคำขอแรก | `429 rate_limit_exceeded` และเฮดเดอร์ `Retry-After`; การปฏิเสธ 5xx ของเกตเวย์ไม่นับโควตา |
| คำขอพร้อมกันของบัญชี | ถูกจำกัด | ส่วนเกินรอในคิว; ถ้ารอไม่ทัน — `429 queue_timeout` |
| ขนาดบอดี้ของคำขอ | 16 MiB | `413` |
| ความยาวคำตอบ | [ตามโมเดล — ตารางด้านล่าง](https://gate.joingonka.ai/th/docs/errors#max-tokens) | เกินเพดานโมเดล — ถูกตัดถึงเพดาน โดยไม่มีข้อผิดพลาด |
| คีย์ลูก | สูงสุด 50 ต่อคีย์ควบคุม, สูงสุด 120 คำขอต่อนาทีต่อคีย์ | เพิ่มเพดาน — ผ่านฝ่ายสนับสนุน |

### ความยาวคำตอบตามโมเดล

ถ้าไม่มี `max_tokens` เกตเวย์จะใส่ค่าเริ่มต้น: แบบไม่สตรีม — สั้นลงเพื่อให้คำตอบอยู่ในไทม์เอาต์, ในสตรีม — เพดานของโมเดล `max_completion_tokens` — ฟิลด์เดียวกัน

| `model` | เพดาน | ไม่สตรีม | ในสตรีม |
| --- | ---: | ---: | ---: |
| `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 |

## ไทม์เอาต์

| ขั้นตอน | ค่า | สิ่งที่เกิดขึ้น |
| --- | --- | --- |
| รอคิว | 45 วิ | `429 queue_timeout` พร้อมเฮดเดอร์ `Retry-After: 1` |
| จุดเริ่มต้นการตอบกลับของเครือข่าย, สตรีม | 150 วิ | `504 upstream_timeout`; หักค่าประเมินโทเคนอินพุต |
| จุดเริ่มต้นการตอบกลับของเครือข่าย, ไม่สตรีม | 150 วิ | `504 upstream_timeout`; หักค่าประเมินโทเคนอินพุต |
| การสร้างคำตอบ | ≈ 300 วิ | เครือข่ายตัดการสร้าง: คำตอบมาพร้อม `finish_reason: length` — ทำต่อด้วยคำขอถัดไป |
| ช่วงหยุดระหว่างชังก์ของสตรีม | 30 วิ | สตรีมถูกปิด: `finish_reason: stop` ในชังก์ `joingonka-stream-stalled` |
| สัญญาณมีชีวิตในสตรีม | 15 วิ | คอมเมนต์ `: keep-alive` — ไคลเอนต์ SSE จะข้ามไป |
| การเปิดสตรีม | 30 วิ | ก่อนจุดนี้การปฏิเสธมาพร้อมรหัสการตอบกลับ หลังจากนั้นมาพร้อมชังก์ `joingonka-error` |
| การตอบกลับเร็วแบบไม่สตรีม | 90 วิ | เกตเวย์ส่ง `200` และส่งช่องว่างทุก 15 วิ — JSON ยังคงถูกต้อง; ข้อผิดพลาดหลังจากนั้นมาพร้อมบอดี้ที่มีฟิลด์ `error` สถานะยังคงเป็น `200` |

> **สิ่งที่ถูกหักเมื่อไทม์เอาต์**
>
> คำขอที่เครือข่ายรับไปแล้วไม่สามารถยกเลิกได้ เมื่อเกิด `504 upstream_timeout` จะถูกหักค่าประเมินโทเค็นอินพุต แต่โทเค็นเอาต์พุตไม่ถูกหัก การลองใหม่คือการหักเงินใหม่ สตรีมที่ถูกตัดก่อนถึง `usage` สุดท้ายก็คิดค่าใช้จ่ายเช่นเดียวกัน หากต้องการคำตอบยาว ๆ ให้ใช้ `stream: true`

## รหัสข้อผิดพลาด

เนื้อความข้อผิดพลาดคือออบเจ็กต์ `error` ที่มีฟิลด์ `message, type, code, param` บางฟิลด์ไม่มีในทุกข้อผิดพลาด ให้ดูที่สถานะและ `type` เป็นหลัก และตรวจสอบเพิ่มเติมจาก `code` เนื่องจากข้อความ `message` อาจเปลี่ยนแปลงได้ รูปแบบ Anthropic อยู่ในหัวข้อ [รูปแบบข้อผิดพลาดของ Anthropic](https://gate.joingonka.ai/th/docs/errors#anthropic-errors)

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

| การตอบกลับ | เมื่อไหร่ | สิ่งที่ต้องทำ |
| --- | --- | --- |
| 400 `invalid_request_error` | เนื้อความไม่ถูกต้อง: ไม่มี `messages` ข้อความเป็นออบเจ็กต์ไม่ได้ เนื้อความไม่ใช่ JSON หรือโมเดลไม่รู้จัก — จะมี `param`: `model` พร้อมรายการโมเดลที่ใช้ได้ในข้อความ | แก้ไขคำขอตามข้อความข้อผิดพลาด |
| 400 `invalid_request_error` `empty_content_after_normalization` | ข้อความว่างเปล่าหลังการปรับมาตรฐาน เช่น มีเพียงรูปภาพ | เพิ่มข้อความลงในข้อความ |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | ใช้ปลั๊กอิน `web` และ `privacy-sanitization` ในคำขอเดียวกัน | เลือกใช้เพียงอย่างใดอย่างหนึ่ง |
| 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: การอ้างอิงถึงคำตอบที่บันทึกไว้ บทสนทนา หรือรายการ โหมดเบื้องหลัง หรือการเรียกใช้เครื่องมือในตัว | ส่งประวัติทั้งหมดมาใน `input` |
| 400 `api_error` | เครือข่ายปฏิเสธพารามิเตอร์ เช่น ค่า `reasoning_effort` อยู่นอกรายการของเครือข่าย | แก้ไขค่าตามข้อความข้อผิดพลาด |
| 401 `authentication_error` | ไม่พบคีย์ ถูกเพิกถอน หรือรูปแบบไม่รู้จัก | ตรวจสอบคีย์ที่หน้า [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | ยอดคงเหลือไม่พอสำหรับการประเมินคำขอ ยอดที่เหลือดูได้ใน `balance_ngonka` | เติมเงิน: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | คำขอที่ไม่มีคีย์และไม่ได้มาจากเว็บไซต์ (`is_demo: true`) | ส่ง API key |
| 402 `child_key_limit_exceeded` | เกินขีดจำกัดการใช้จ่ายของคีย์ — รายวัน รายเดือน หรือทั้งหมด ยอดที่เหลือดูได้ใน `daily_remaining, monthly_remaining, total_remaining` | เพิ่มขีดจำกัดคีย์ที่หน้า [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) หรือรอให้รีเซ็ต |
| 403 `forbidden` | ใช้คีย์จัดการ `gm-` ในคำขอไปยังโมเดล หรือใช้ API key บนเส้นทางเฉพาะแดชบอร์ด | สำหรับคำขอให้ใช้คีย์ `jg-` หรือ `gc-` ส่วนการจัดการบัญชีให้ทำในแดชบอร์ด |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: ไม่มีโมเดลในแคตตาล็อกหรือถูกซ่อนไว้ชั่วคราว | ใช้ id จาก `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` และที่อยู่อื่น ๆ ที่เก็บสถานะ, `/v1/responses/compact` | เก็บประวัติไว้เอง สำหรับ Codex CLI ให้ตั้งค่า id ผู้ให้บริการของคุณเอง |
| 404 `invalid_request_error` | เส้นทางไม่รู้จัก | ตรวจสอบเมธอด เส้นทาง และที่อยู่ฐาน |
| 413 `invalid_request_error` | เนื้อความคำขอเกินขีดจำกัด | ลดขนาดคำขอ |
| 415 `invalid_request_error` | เนื้อความไม่ใช่ JSON ตามเฮดเดอร์ ต้องใช้ `Content-Type: application/json` | ส่ง `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | เกินจำนวนคำขอต่อนาทีต่อคีย์ ในเนื้อความมี `rate_limit` พร้อม `limit, remaining, reset` | รอตามจำนวนวินาทีที่ระบุใน `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | โมเดลโอเวอร์โหลดในเครือข่าย Gonka | ลองใหม่หลัง `Retry-After` หรือเลือกโมเดลอื่น — [โมเดล](https://gate.joingonka.ai/th/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | ที่นั่งเชื่อมต่อเครือข่ายเต็มทั้งหมด คิวเต็มหรือหมดเวลารอ | ลองใหม่หลัง `Retry-After` |
| 500 `server_error` | ข้อผิดพลาดภายในของเกตเวย์ | ลองใหม่ภายหลัง หากยังเกิดซ้ำให้ติดต่อฝ่ายสนับสนุนพร้อมแนบ `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings`: ไม่มีโมเดลเอ็มเบดดิ้งในเครือข่าย | ใช้บริการเอ็มเบดดิ้งอื่น |
| 502 `api_error` `upstream_unauthorized` | ผู้ให้บริการในเครือข่ายปฏิเสธข้อมูลรับรองของเกตเวย์ คีย์ของคุณยังปกติดี | ลองใหม่ในอีกหนึ่งนาที |
| 502 `api_error` | ข้อผิดพลาดของเครือข่าย Gonka `code` มาจากเครือข่ายหากเครือข่ายส่งมา | ลองใหม่โดยเว้นช่วง หรือเลือกโมเดลอื่น |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | โมเดลไม่พร้อมใช้งานในขณะนี้จากการตรวจสอบของเครือข่าย: เกิดข้อขัดข้อง กำลังเริ่มต้น ไม่เสถียร หรือไม่มีใครให้บริการ ปฏิเสธทันทีโดยไม่รอ | เลือกโมเดลอื่น — ข้อความข้อผิดพลาดจะบอกว่าใช้ตัวไหนได้ รายการดูได้ที่ [โมเดล](https://gate.joingonka.ai/th/docs/models) |
| 503 `service_unavailable` | ไม่มีโหนดที่ใช้งานได้ | ลองใหม่ภายหลัง |
| 504 `timeout` `upstream_timeout` | เครือข่ายรับคำขอแล้วแต่ไม่ตอบกลับทันเวลา มีการหักค่าประเมินโทเค็นอินพุตแล้ว | สำหรับคำตอบยาว ๆ ให้ใช้ `stream: true` การลองใหม่คือการหักเงินใหม่ |

## ข้อผิดพลาดในสตรีมที่เปิดอยู่

ก่อนที่สตรีมจะเปิด การปฏิเสธจะมาในรูปโค้ดตอบกลับปกติเหมือนไม่มีสตรีม หลังจากเปิดแล้ว สถานะจะเป็น `200` และข้อผิดพลาดจะมาในรูปแบบนี้:

- Chat Completions — ชังก์ `joingonka-error` พร้อมฟิลด์ `error` จากนั้นตัดขาดโดยไม่มี `[DONE]`
- แบบไม่มีสตรีมหลังการตอบกลับช่วงต้น — สถานะ `200` และเนื้อความที่มีฟิลด์ `error`
- Anthropic Messages — อีเวนต์ `event: error` จากนั้นสตรีมปิดลง
- OpenAI Responses — อีเวนต์ `response.failed` สาเหตุอยู่ใน `response.error.code`
- Legacy Completions — `data: {"error": …}` จากนั้น `[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

- `POST /v1/messages` ตอบกลับด้วยซอง Anthropic: `{"type": "error", "error": {"type", "message"}}`
- การปฏิเสธของเกตเวย์ยังคงใช้ `type` จากตารางด้านบน (`insufficient_funds`, `model_unavailable` และอื่น ๆ) ในซองนี้ไม่มีฟิลด์ `code` — สาเหตุอยู่ในข้อความ
- ข้อผิดพลาดของรูปแบบคำขอ — `invalid_request_error`: ไม่มีข้อความหรือ `max_tokens` เรียกใช้เครื่องมือโดยไม่มีชื่อ โมเดลไม่รู้จัก
- เส้นทางไม่รู้จัก — `not_found_error` เนื้อความใหญ่เกินไป — `request_too_large`

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

## อะไรควรลองใหม่

- หลังเว้นช่วงตาม `Retry-After`: `429`
- ด้วยการเว้นช่วงเพิ่มขึ้นเรื่อย ๆ — 1, 2, 4 วินาที และต่อไป: `500`, `502`, `503 service_unavailable`, `504`
- ด้วยโมเดลอื่น: `503 model_unavailable`
- อย่าลองใหม่โดยไม่เปลี่ยนแปลง — แก้ไขคำขอ คีย์ หรือยอดคงเหลือ: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

การลองใหม่ทุกครั้งหลัง `504` คือการหักค่าประเมินอินพุตใหม่ สำหรับคำตอบยาว ๆ ให้เปิด `stream: true`

หากข้อผิดพลาดเกิดซ้ำ ให้ติดต่อฝ่ายสนับสนุนพร้อมแนบ `x-request-id` จากเฮดเดอร์ของการตอบกลับ