> Dành cho AI agent: hướng dẫn từng bước để thiết lập — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), chỉ mục tài liệu — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Lỗi và giới hạn

Giới hạn yêu cầu, thời gian chờ và mã lỗi của gateway. Với mỗi phản hồi, chúng tôi nêu rõ khi nào nó xảy ra và cần làm gì: thử lại yêu cầu hay sửa lại yêu cầu.

## Giới hạn

Các con số — từ trường `limits` trong phản hồi `GET /v1/capabilities`: ở đó luôn có giá trị mới nhất.

| Giới hạn | Giá trị | Khi vượt quá |
| --- | --- | --- |
| Số yêu cầu mỗi phút trên mỗi key | 120, cửa sổ 60 giây tính từ yêu cầu đầu tiên | `429 rate_limit_exceeded` và header `Retry-After`; các lỗi 5xx của gateway không tiêu tốn hạn mức |
| Số yêu cầu đồng thời của tài khoản | có giới hạn | các yêu cầu dư sẽ chờ trong hàng đợi; nếu không chờ được — `429 queue_timeout` |
| Kích thước body của yêu cầu | 16 MiB | `413` |
| Độ dài phản hồi | [theo model — bảng bên dưới](https://gate.joingonka.ai/vi/docs/errors#max-tokens) | vượt mức trần của model — bị cắt xuống mức trần, không báo lỗi |
| Key con | tối đa 50 cho mỗi key quản lý, mỗi key tối đa 120 yêu cầu mỗi phút | để nâng mức trần — hãy liên hệ hỗ trợ |

### Độ dài phản hồi theo model

Không có `max_tokens`, gateway sẽ dùng giá trị mặc định: không streaming — ngắn hơn, để phản hồi kịp trong thời gian timeout, khi streaming — mức trần của model. `max_completion_tokens` — cùng một trường.

| `model` | Mức trần | Không streaming | Khi 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

| Giai đoạn | Giá trị | Điều gì xảy ra |
| --- | --- | --- |
| Chờ có chỗ trong hàng đợi | 45 giây | `429 queue_timeout` với header `Retry-After: 1` |
| Bắt đầu phản hồi từ mạng, streaming | 150 giây | `504 upstream_timeout`; sẽ trừ ước tính token đầu vào |
| Bắt đầu phản hồi từ mạng, không streaming | 150 giây | `504 upstream_timeout`; sẽ trừ ước tính token đầu vào |
| Tạo phản hồi | ≈ 300 giây | mạng ngắt quá trình tạo: phản hồi đến với `finish_reason: length` — hãy tiếp tục bằng yêu cầu tiếp theo |
| Khoảng nghỉ giữa các chunk của stream | 30 giây | luồng bị đóng: `finish_reason: stop` trong chunk `joingonka-stream-stalled` |
| Tín hiệu hoạt động trong stream | 15 giây | comment `: keep-alive` — các client SSE sẽ bỏ qua nó |
| Mở luồng | 30 giây | trước thời điểm này lỗi đến dưới dạng mã phản hồi, sau đó — dưới dạng chunk `joingonka-error` |
| Phản hồi sớm không streaming | 90 giây | gateway trả về `200` và cứ mỗi 15 giây lại gửi khoảng trắng — JSON vẫn hợp lệ; lỗi sau đó đến trong body với trường `error`, trạng thái vẫn là `200` |

> **Sẽ trừ gì khi timeout**
>
> Yêu cầu đã được mạng chấp nhận thì không thể hủy. Khi `504 upstream_timeout`, phần ước tính token đầu vào vẫn bị trừ, token đầu ra thì không; gửi lại là một lần trừ mới. Luồng bị ngắt trước `usage` cuối cùng cũng bị tính phí như vậy. Với câu trả lời dài, hãy dùng `stream: true`.

## Mã lỗi

Phần thân lỗi là một đối tượng `error` với các trường `message, type, code, param`; không phải lỗi nào cũng có đủ các trường. Hãy dựa vào trạng thái và `type`, đối chiếu thêm bằng `code`: nội dung `message` có thể thay đổi. Định dạng Anthropic nằm ở mục [Định dạng lỗi Anthropic](https://gate.joingonka.ai/vi/docs/errors#anthropic-errors).

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

| Phản hồi | Khi nào | Cần làm gì |
| --- | --- | --- |
| 400 `invalid_request_error` | Thân yêu cầu không hợp lệ: thiếu `messages`, message không phải đối tượng, thân không phải JSON; model không xác định — kèm `param`: `model` và danh sách model khả dụng trong nội dung | Sửa yêu cầu theo nội dung lỗi |
| 400 `invalid_request_error` `empty_content_after_normalization` | Message trống sau khi chuẩn hóa — ví dụ chỉ có một hình ảnh | Thêm văn bản vào message |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Plugin `web` và `privacy-sanitization` trong cùng một yêu cầu | Chỉ giữ lại một trong hai |
| 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: tham chiếu đến câu trả lời, hội thoại hoặc phần tử đã lưu; chế độ nền; yêu cầu công cụ tích hợp | Gửi toàn bộ lịch sử trong `input` |
| 400 `api_error` | Mạng từ chối tham số — ví dụ giá trị `reasoning_effort` nằm ngoài danh sách của mạng | Sửa giá trị theo nội dung lỗi |
| 401 `authentication_error` | Không tìm thấy key, key đã bị thu hồi hoặc sai định dạng | Kiểm tra key tại trang [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | Số dư không đủ cho ước tính của yêu cầu; số còn lại nằm ở `balance_ngonka` | Nạp thêm số dư: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Yêu cầu không có key không đến từ website (`is_demo: true`) | Truyền API key |
| 402 `child_key_limit_exceeded` | Vượt hạn mức chi tiêu của key — theo ngày, theo tháng hoặc tổng; số còn lại nằm ở `daily_remaining, monthly_remaining, total_remaining` | Nâng hạn mức key tại trang [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) hoặc chờ reset |
| 403 `forbidden` | Key quản trị `gm-` trong yêu cầu gọi model; API key dùng cho route chỉ dành cho trang quản lý | Với yêu cầu, dùng key `jg-` hoặc `gc-`; quản lý tài khoản — trong trang quản lý |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: model không có trong danh mục hoặc tạm thời bị ẩn | Lấy id từ `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` và các địa chỉ trạng thái khác, `/v1/responses/compact` | Tự lưu lịch sử; với Codex CLI hãy đặt id provider riêng |
| 404 `invalid_request_error` | Đường dẫn không xác định | Kiểm tra phương thức, đường dẫn và địa chỉ cơ sở |
| 413 `invalid_request_error` | Thân yêu cầu vượt giới hạn | Rút gọn yêu cầu |
| 415 `invalid_request_error` | Thân không phải JSON theo header: cần `Content-Type: application/json` | Gửi `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | Vượt số yêu cầu mỗi phút trên mỗi key; trong thân có `rate_limit` với `limit, remaining, reset` | Chờ đúng số giây trong `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Model bị quá tải trên mạng Gonka | Thử lại sau `Retry-After` hoặc chọn model khác — [Mô hình](https://gate.joingonka.ai/vi/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Hết chỗ kết nối mạng: hàng đợi đầy hoặc đã hết thời gian chờ | Thử lại sau `Retry-After` |
| 500 `server_error` | Lỗi nội bộ của gateway | Thử lại sau; nếu lặp lại, hãy liên hệ hỗ trợ và kèm `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings`: mạng không có model embedding | Dùng dịch vụ embedding khác |
| 502 `api_error` `upstream_unauthorized` | Provider của mạng từ chối thông tin xác thực của gateway — key của bạn vẫn ổn | Thử lại sau một phút |
| 502 `api_error` | Lỗi mạng Gonka; `code` đến từ mạng, nếu mạng có gửi kèm | Thử lại sau một khoảng nghỉ hoặc chọn model khác |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | Model hiện không khả dụng theo kiểm tra của mạng: sự cố, đang khởi động, không ổn định hoặc không ai vận hành; từ chối ngay, không chờ | Chọn model khác — nội dung lỗi sẽ gợi ý; danh sách ở [Mô hình](https://gate.joingonka.ai/vi/docs/models) |
| 503 `service_unavailable` | Không có node khả dụng | Thử lại sau |
| 504 `timeout` `upstream_timeout` | Mạng đã nhận yêu cầu nhưng không phản hồi kịp; phần ước tính token đầu vào đã bị trừ | Với câu trả lời dài, dùng `stream: true`; gửi lại là một lần trừ mới |

## Lỗi trong luồng đang mở

Khi luồng chưa mở, lỗi từ chối đến dưới dạng mã phản hồi thông thường — như khi không dùng stream. Sau khi mở, trạng thái đã là `200`, và lỗi đến như sau:

- Chat Completions — chunk `joingonka-error` với trường `error`, rồi ngắt kết nối mà không có `[DONE]`.
- Không dùng stream sau phản hồi sớm — trạng thái `200` và thân có trường `error`.
- Anthropic Messages — sự kiện `event: error`, rồi luồng đóng lại.
- OpenAI Responses — sự kiện `response.failed`, nguyên nhân ở `response.error.code`.
- Legacy Completions — `data: {"error": …}`, rồi `[DONE]`.

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

## Định dạng lỗi Anthropic

- `POST /v1/messages` phản hồi bằng envelope Anthropic: `{"type": "error", "error": {"type", "message"}}`.
- Lỗi từ chối của gateway giữ nguyên `type` từ bảng trên (`insufficient_funds`, `model_unavailable` và các loại khác); không có trường `code` trong envelope này — nguyên nhân nằm trong nội dung.
- Lỗi hình thức yêu cầu — `invalid_request_error`: thiếu message hoặc `max_tokens`, gọi công cụ không có tên, model không xác định.
- Đường dẫn không xác định — `not_found_error`, thân quá lớn — `request_too_large`.

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

## Khi nào nên thử lại

- Sau khoảng nghỉ trong `Retry-After`: `429`
- Với khoảng nghỉ tăng dần — 1, 2, 4 giây và tiếp tục: `500`, `502`, `503 service_unavailable`, `504`
- Với model khác: `503 model_unavailable`
- Không thử lại nguyên trạng — hãy sửa yêu cầu, key hoặc số dư: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

Mỗi lần thử lại sau `504` là một lần trừ mới cho ước tính đầu vào; với câu trả lời dài, hãy bật `stream: true`.

Lỗi lặp lại — hãy liên hệ hỗ trợ và kèm `x-request-id` từ header phản hồi.